bigdatacloud 1.0.0__tar.gz

bigdatacloud-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BigDataCloud Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bigdatacloud-1.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: bigdatacloud
+Version: 1.0.0
+Summary: Official Python SDK for BigDataCloud APIs — IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering
+Author-email: BigDataCloud Pty Ltd <support@bigdatacloud.com>
+License: MIT
+Project-URL: Homepage, https://www.bigdatacloud.com
+Project-URL: Documentation, https://www.bigdatacloud.com/docs/sdks
+Project-URL: Repository, https://github.com/bigdatacloudapi/bigdatacloud-python
+Keywords: ip-geolocation,reverse-geocoding,bigdatacloud,geolocation,network-engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Dynamic: license-file
+
+# BigDataCloud Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/bigdatacloud)](https://pypi.org/project/bigdatacloud/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Official Python SDK for [BigDataCloud](https://www.bigdatacloud.com) APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering — plus a GraphQL interface for all packages.
+
+## Installation
+
+```bash
+pip install bigdatacloud
+```
+
+## API Key
+
+Get a free API key at [bigdatacloud.com/login](https://www.bigdatacloud.com/login). No credit card required.
+
+Store your key in the `BIGDATACLOUD_API_KEY` environment variable:
+
+```bash
+export BIGDATACLOUD_API_KEY=your-key-here
+```
+
+## Quick Start
+
+```python
+from bigdatacloud import BigDataCloudClient
+
+# Reads BIGDATACLOUD_API_KEY from environment
+client = BigDataCloudClient.from_environment()
+
+# Or pass the key directly
+# client = BigDataCloudClient("your-key-here")
+
+# IP Geolocation
+geo = client.ip_geolocation.get("1.1.1.1")
+print(f"{geo.location.city}, {geo.country.name}")
+
+# Full geolocation with hazard report
+full = client.ip_geolocation.get_full("1.1.1.1")
+print(f"Security: {full.security_threat}")
+print(f"Is Tor:   {full.hazard_report.is_known_as_tor_server}")
+
+# Reverse Geocoding
+place = client.reverse_geocoding.reverse_geocode(-33.87, 151.21)
+print(f"{place.city}, {place.principal_subdivision}, {place.country_name}")
+
+# Phone Validation
+phone = client.verification.validate_phone("+61412345678", "AU")
+print(f"Valid: {phone.is_valid}, Type: {phone.line_type}")
+
+# Email Verification
+email = client.verification.verify_email("user@example.com")
+print(f"Valid: {email.is_valid}, Disposable: {email.is_disposable}")
+```
+
+## Context Manager
+
+```python
+with BigDataCloudClient.from_environment() as client:
+    geo = client.ip_geolocation.get("1.1.1.1")
+```
+
+## Confidence Area
+
+The `confidence_area` field may encode multiple polygons. Use the helper:
+
+```python
+from bigdatacloud import split_into_polygons
+
+geo = client.ip_geolocation.get_with_confidence_area("1.1.1.1")
+polygons = split_into_polygons(geo.confidence_area)
+for ring in polygons:
+    print(f"Polygon with {len(ring)} points")
+```
+
+## GraphQL
+
+BigDataCloud is the only IP geolocation provider with a GraphQL interface. Use the fluent builders to select exactly the fields you need:
+
+```python
+# Select only city, country flag, and confidence
+result = client.graphql.ip_geolocation.ip_data("1.1.1.1",
+    lambda q: q.locality().country(lambda c: c.flag_emoji()).confidence())
+
+print(result["locality"]["city"])
+
+# Reverse geocoding with timezone
+loc = client.graphql.reverse_geocoding.location_data(-33.87, 151.21,
+    lambda q: q.locality().country().timezone())
+
+# Phone & Email
+email = client.graphql.verification.email_verification("user@example.com")
+phone = client.graphql.verification.phone_number("+61412345678")
+
+# Network Engineering
+asn = client.graphql.network_engineering.asn_info_full("AS13335",
+    lambda q: q.basic_info().receiving_from())
+```
+
+Raw queries are also supported:
+
+```python
+data = client.graphql.ip_geolocation.query_raw("""
+{
+    ipData(ip: "1.1.1.1") {
+        locality { city }
+        country { name }
+    }
+}
+""")
+```
+
+## Available APIs
+
+| Client | Key Methods |
+|--------|-------------|
+| `client.ip_geolocation` | `get`, `get_with_confidence_area`, `get_full`, `get_country_by_ip`, `get_country_info`, `get_all_countries`, `get_hazard_report`, `get_user_risk`, `get_asn_info`, `get_network_by_ip`, `get_timezone_by_iana_id`, `get_timezone_by_ip`, `parse_user_agent` |
+| `client.reverse_geocoding` | `reverse_geocode`, `reverse_geocode_with_timezone`, `get_timezone_by_location` |
+| `client.verification` | `validate_phone`, `validate_phone_by_ip`, `verify_email` |
+| `client.network_engineering` | `get_asn_info_extended`, `get_receiving_from`, `get_transit_to`, `get_bgp_prefixes`, `get_networks_by_cidr`, `get_asn_rank_list`, `get_tor_exit_nodes` |
+| `client.graphql.ip_geolocation` | `ip_data`, `country_info`, `user_agent`, `timezone_info`, `query_raw` |
+| `client.graphql.reverse_geocoding` | `location_data`, `query_raw` |
+| `client.graphql.verification` | `email_verification`, `phone_number`, `query_raw` |
+| `client.graphql.network_engineering` | `asn_info_full`, `network_by_ip`, `query_raw` |
+
+## Samples
+
+```bash
+python samples/ip_geolocation.py
+python samples/reverse_geocoding.py
+python samples/verification.py
+python samples/network_engineering.py
+python samples/graphql_sample.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bigdatacloud-1.0.0/README.md

@@ -0,0 +1,139 @@
+# BigDataCloud Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/bigdatacloud)](https://pypi.org/project/bigdatacloud/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Official Python SDK for [BigDataCloud](https://www.bigdatacloud.com) APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering — plus a GraphQL interface for all packages.
+
+## Installation
+
+```bash
+pip install bigdatacloud
+```
+
+## API Key
+
+Get a free API key at [bigdatacloud.com/login](https://www.bigdatacloud.com/login). No credit card required.
+
+Store your key in the `BIGDATACLOUD_API_KEY` environment variable:
+
+```bash
+export BIGDATACLOUD_API_KEY=your-key-here
+```
+
+## Quick Start
+
+```python
+from bigdatacloud import BigDataCloudClient
+
+# Reads BIGDATACLOUD_API_KEY from environment
+client = BigDataCloudClient.from_environment()
+
+# Or pass the key directly
+# client = BigDataCloudClient("your-key-here")
+
+# IP Geolocation
+geo = client.ip_geolocation.get("1.1.1.1")
+print(f"{geo.location.city}, {geo.country.name}")
+
+# Full geolocation with hazard report
+full = client.ip_geolocation.get_full("1.1.1.1")
+print(f"Security: {full.security_threat}")
+print(f"Is Tor:   {full.hazard_report.is_known_as_tor_server}")
+
+# Reverse Geocoding
+place = client.reverse_geocoding.reverse_geocode(-33.87, 151.21)
+print(f"{place.city}, {place.principal_subdivision}, {place.country_name}")
+
+# Phone Validation
+phone = client.verification.validate_phone("+61412345678", "AU")
+print(f"Valid: {phone.is_valid}, Type: {phone.line_type}")
+
+# Email Verification
+email = client.verification.verify_email("user@example.com")
+print(f"Valid: {email.is_valid}, Disposable: {email.is_disposable}")
+```
+
+## Context Manager
+
+```python
+with BigDataCloudClient.from_environment() as client:
+    geo = client.ip_geolocation.get("1.1.1.1")
+```
+
+## Confidence Area
+
+The `confidence_area` field may encode multiple polygons. Use the helper:
+
+```python
+from bigdatacloud import split_into_polygons
+
+geo = client.ip_geolocation.get_with_confidence_area("1.1.1.1")
+polygons = split_into_polygons(geo.confidence_area)
+for ring in polygons:
+    print(f"Polygon with {len(ring)} points")
+```
+
+## GraphQL
+
+BigDataCloud is the only IP geolocation provider with a GraphQL interface. Use the fluent builders to select exactly the fields you need:
+
+```python
+# Select only city, country flag, and confidence
+result = client.graphql.ip_geolocation.ip_data("1.1.1.1",
+    lambda q: q.locality().country(lambda c: c.flag_emoji()).confidence())
+
+print(result["locality"]["city"])
+
+# Reverse geocoding with timezone
+loc = client.graphql.reverse_geocoding.location_data(-33.87, 151.21,
+    lambda q: q.locality().country().timezone())
+
+# Phone & Email
+email = client.graphql.verification.email_verification("user@example.com")
+phone = client.graphql.verification.phone_number("+61412345678")
+
+# Network Engineering
+asn = client.graphql.network_engineering.asn_info_full("AS13335",
+    lambda q: q.basic_info().receiving_from())
+```
+
+Raw queries are also supported:
+
+```python
+data = client.graphql.ip_geolocation.query_raw("""
+{
+    ipData(ip: "1.1.1.1") {
+        locality { city }
+        country { name }
+    }
+}
+""")
+```
+
+## Available APIs
+
+| Client | Key Methods |
+|--------|-------------|
+| `client.ip_geolocation` | `get`, `get_with_confidence_area`, `get_full`, `get_country_by_ip`, `get_country_info`, `get_all_countries`, `get_hazard_report`, `get_user_risk`, `get_asn_info`, `get_network_by_ip`, `get_timezone_by_iana_id`, `get_timezone_by_ip`, `parse_user_agent` |
+| `client.reverse_geocoding` | `reverse_geocode`, `reverse_geocode_with_timezone`, `get_timezone_by_location` |
+| `client.verification` | `validate_phone`, `validate_phone_by_ip`, `verify_email` |
+| `client.network_engineering` | `get_asn_info_extended`, `get_receiving_from`, `get_transit_to`, `get_bgp_prefixes`, `get_networks_by_cidr`, `get_asn_rank_list`, `get_tor_exit_nodes` |
+| `client.graphql.ip_geolocation` | `ip_data`, `country_info`, `user_agent`, `timezone_info`, `query_raw` |
+| `client.graphql.reverse_geocoding` | `location_data`, `query_raw` |
+| `client.graphql.verification` | `email_verification`, `phone_number`, `query_raw` |
+| `client.graphql.network_engineering` | `asn_info_full`, `network_by_ip`, `query_raw` |
+
+## Samples
+
+```bash
+python samples/ip_geolocation.py
+python samples/reverse_geocoding.py
+python samples/verification.py
+python samples/network_engineering.py
+python samples/graphql_sample.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bigdatacloud-1.0.0/bigdatacloud/__init__.py

@@ -0,0 +1,23 @@
+"""
+BigDataCloud Python SDK
+Official client for BigDataCloud APIs.
+
+Quick start::
+
+    from bigdatacloud import BigDataCloudClient
+
+    client = BigDataCloudClient.from_environment()
+    geo = client.ip_geolocation.get("1.1.1.1")
+    print(f"{geo.location.city}, {geo.country.name}")
+"""
+from .client import BigDataCloudClient, BigDataCloudException
+from .confidence_area import split_into_polygons, is_multi_polygon
+from .models import *
+
+__version__ = "1.0.0"
+__all__ = [
+    "BigDataCloudClient",
+    "BigDataCloudException",
+    "split_into_polygons",
+    "is_multi_polygon",
+]

bigdatacloud-1.0.0/bigdatacloud/_deserialise.py

@@ -0,0 +1,113 @@
+"""
+Lightweight JSON → dataclass deserialiser.
+Converts snake_case and camelCase field names automatically.
+"""
+from __future__ import annotations
+import re
+from typing import Any, Dict, List, Optional, Type, TypeVar, get_type_hints
+import dataclasses
+
+T = TypeVar("T")
+
+
+def _to_snake(name: str) -> str:
+    """Convert camelCase or PascalCase to snake_case."""
+    s1 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+
+def _get_origin(tp: Any) -> Any:
+    return getattr(tp, "__origin__", None)
+
+
+def _get_args(tp: Any) -> tuple:
+    return getattr(tp, "__args__", ())
+
+
+def from_dict(cls: Type[T], data: Optional[Dict[str, Any]]) -> Optional[T]:
+    """Deserialise a dict into a dataclass instance, handling nested types."""
+    if data is None:
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    if not dataclasses.is_dataclass(cls):
+        return data  # type: ignore
+
+    try:
+        hints = get_type_hints(cls)
+    except Exception:
+        # Fall back to field annotations if get_type_hints fails (forward refs etc.)
+        hints = {f.name: f.type for f in dataclasses.fields(cls)}  # type: ignore
+    kwargs: Dict[str, Any] = {}
+
+    for f in dataclasses.fields(cls):  # type: ignore
+        field_name = f.name  # snake_case field name
+        # Try snake_case first, then camelCase variants
+        camel = re.sub(r"_([a-z])", lambda m: m.group(1).upper(), field_name)
+        # Special: i_cloud → iCloud
+        camel2 = re.sub(r"_([A-Z])", lambda m: m.group(1), camel)
+
+        raw = data.get(field_name) or data.get(camel) or data.get(camel2)
+
+        if raw is None:
+            # Use the default
+            kwargs[field_name] = f.default if f.default is not dataclasses.MISSING else (
+                f.default_factory() if f.default_factory is not dataclasses.MISSING else None  # type: ignore
+            )
+            continue
+
+        field_type = hints.get(field_name)
+        kwargs[field_name] = _convert(raw, field_type)
+
+    return cls(**kwargs)  # type: ignore
+
+
+def _convert(value: Any, tp: Any) -> Any:
+    """Recursively convert value to the target type."""
+    if tp is None or value is None:
+        return value
+
+    origin = _get_origin(tp)
+    args = _get_args(tp)
+
+    # Optional[X] → unwrap
+    if origin is type(None):
+        return None
+    if str(origin) in ("<class 'typing.Union'>", "typing.Union") or (
+        hasattr(tp, "__origin__") and tp.__origin__ is type(None)
+    ):
+        # Handle Optional properly
+        pass
+
+    # Check for Union (Optional is Union[X, None])
+    import typing
+    if hasattr(typing, "get_args"):
+        actual_args = typing.get_args(tp)
+        actual_origin = typing.get_origin(tp)
+        if actual_origin is typing.Union:
+            # Pick the non-None type
+            non_none = [a for a in actual_args if a is not type(None)]
+            if non_none:
+                return _convert(value, non_none[0])
+            return value
+
+    # List[X]
+    if origin is list:
+        item_type = args[0] if args else None
+        if isinstance(value, list):
+            return [_convert(item, item_type) for item in value]
+        return []
+
+    # Dataclass
+    if dataclasses.is_dataclass(tp) and isinstance(value, dict):
+        return from_dict(tp, value)
+
+    # Primitives
+    if tp in (int, float, str, bool) and value is not None:
+        try:
+            return tp(value)
+        except (ValueError, TypeError):
+            return value
+
+    return value