pybgpkit 0.8.0__tar.gz → 0.9.0__tar.gz

{pybgpkit-0.8.0/pybgpkit.egg-info → pybgpkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybgpkit
-Version: 0.8.0
+Version: 0.9.0
 Summary: BGPKIT tools Python bindings
 Author-email: Mingwei Zhang <mingwei@bgpkit.com>
 License-Expression: MIT

{pybgpkit-0.8.0 → pybgpkit-0.9.0}/bgpkit/__init__.py

@@ -1,4 +1,5 @@
 from .bgpkit_parser import Filter, Parser, RouteElem, RouteParser
+from ._utils import BGPKITApiError
 from .bgpkit_broker import Broker, BrokerItem, CollectorItem, PeerItem
 from .bgpkit_roas import Roas, RoasItem
 from .bgpkit_ip import IpLookup, IpInfo

pybgpkit-0.9.0/bgpkit/_utils.py

@@ -0,0 +1,39 @@
+"""Shared helpers for the BGPKIT API clients."""
+
+from dataclasses import fields
+from typing import Optional
+
+import requests
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class BGPKITApiError(RuntimeError):
+    """Raised when an API request fails or returns an error response."""
+
+
+def from_item(cls, item: dict):
+    """Build a dataclass from an API item, ignoring unknown fields."""
+    names = {field.name for field in fields(cls)}
+    return cls(**{key: value for key, value in item.items() if key in names})
+
+
+def request_json(
+    url: str,
+    params: Optional[dict] = None,
+    verify: bool = True,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """GET a JSON API endpoint, raising BGPKITApiError on failures."""
+    try:
+        response = requests.get(url, params=params or {}, verify=verify, timeout=timeout)
+    except requests.RequestException as error:
+        raise BGPKITApiError(f"GET {url} failed: {error}") from error
+    if response.status_code >= 400:
+        raise BGPKITApiError(
+            f"GET {url} failed with HTTP {response.status_code}: {response.text[:200]}"
+        )
+    try:
+        return response.json()
+    except ValueError as error:
+        raise BGPKITApiError(f"GET {url} returned a non-JSON response") from error

pybgpkit-0.9.0/bgpkit/bgpkit_asn.py

@@ -0,0 +1,116 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ._utils import DEFAULT_TIMEOUT, from_item, request_json
+
+
+@dataclass
+class Pagination:
+    page: int = 0
+    page_size: int = 0
+    total_pages: int = 0
+    total_count: int = 0
+    has_next: bool = False
+    has_prev: bool = False
+
+
+@dataclass
+class AsnInfo:
+    asn: int
+    name: str
+    country: str = ""
+    country_name: str = ""
+    org_name: str = ""
+    org_id: str = ""
+    as2org: Optional[dict] = None
+    hegemony: Optional[dict] = None
+    peeringdb: Optional[dict] = None
+    population: Optional[dict] = None
+
+
+@dataclass
+class AsnLookupResult:
+    data: List[AsnInfo]
+    count: int
+    page: int
+    page_size: int
+    updated_at: str = ""
+    pagination: Optional[Pagination] = None
+
+
+class AsnLookup:
+    """BGPKIT ASN information lookup (v3/utils/asn)."""
+
+    def __init__(
+        self,
+        api_url: str = "https://api.bgpkit.com/v3/utils",
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = api_url.rstrip("/")
+        self.timeout = timeout
+
+    def query(
+        self,
+        asn: str = None,
+        country: str = None,
+        search: str = None,
+        page: int = 0,
+        page_size: int = 100,
+    ) -> AsnLookupResult:
+        """Look up ASN information.
+
+        Args:
+            asn: AS number, or a comma-separated list of AS numbers.
+            country: Filter by ISO country code.
+            search: Free-text search over ASN names and organizations.
+            page: Page number to start from (0-indexed).
+            page_size: Results per page.
+
+        Returns:
+            AsnLookupResult with the parsed ASN entries and pagination info.
+        """
+        params = {}
+        if asn:
+            params["asn"] = asn
+        if country:
+            params["country"] = country
+        if search:
+            params["search"] = search
+        if page is not None:
+            params["page"] = page
+        if page_size:
+            params["page_size"] = min(page_size, 10000)
+
+        response = request_json(f"{self.base_url}/asn", params=params, timeout=self.timeout)
+
+        data = []
+        for item in response.get("data", []):
+            as2org = item.get("as2org") if isinstance(item.get("as2org"), dict) else {}
+            data.append(
+                AsnInfo(
+                    asn=item.get("asn"),
+                    name=item.get("name", ""),
+                    country=item.get("country", ""),
+                    country_name=item.get("country_name", ""),
+                    org_name=as2org.get("org_name", ""),
+                    org_id=as2org.get("org_id", ""),
+                    as2org=as2org or None,
+                    hegemony=item.get("hegemony"),
+                    peeringdb=item.get("peeringdb"),
+                    population=item.get("population"),
+                )
+            )
+
+        pagination_data = response.get("pagination")
+        pagination = (
+            from_item(Pagination, pagination_data) if isinstance(pagination_data, dict) else None
+        )
+
+        return AsnLookupResult(
+            data=data,
+            count=response.get("count", 0),
+            page=response.get("page", page),
+            page_size=response.get("page_size", page_size),
+            updated_at=response.get("updatedAt", ""),
+            pagination=pagination,
+        )

pybgpkit-0.9.0/bgpkit/bgpkit_broker.py

@@ -0,0 +1,202 @@
+import json
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+import urllib3
+
+from ._utils import DEFAULT_TIMEOUT, BGPKITApiError, from_item, request_json
+
+DEFAULT_API_URL = "https://api.bgpkit.com/v3/broker"
+
+
+def check_type(value: any, ty: type) -> bool:
+    try:
+        ty(value)
+        return True
+    except (ValueError, TypeError):
+        raise ValueError("invalid option input")
+
+
+@dataclass
+class BrokerItem:
+    ts_start: str
+    ts_end: str
+    collector_id: str
+    data_type: str
+    url: str
+    rough_size: int
+    exact_size: int
+    delay: Optional[float] = None  # seconds since the latest catalog update; /latest items only
+
+
+@dataclass
+class PeerItem:
+    date: str
+    collector: str
+    ip: str
+    asn: int
+    num_v4_pfxs: int
+    num_v6_pfxs: int
+    num_connected_asns: int
+
+    @property
+    def full_feed(self) -> bool:
+        """True for full-table peers (>700k IPv4 or >100k IPv6 prefixes)."""
+        return self.num_v4_pfxs > 700_000 or self.num_v6_pfxs > 100_000
+
+
+@dataclass
+class CollectorItem:
+    name: str
+    project: str
+    data_url: str
+    activated_on: str
+    deactivated_on: Optional[str]
+    country: str
+
+    @property
+    def active(self) -> bool:
+        return self.deactivated_on is None
+
+
+class Broker:
+    """BGPKIT Broker v3 API wrapper.
+
+    Provides access to MRT data file search, peer information,
+    collector metadata, and latest file discovery.
+
+    The API base URL can be overridden per instance with ``api_url`` or for the
+    whole process with the ``BGPKIT_BROKER_URL`` environment variable.
+    """
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        page_size: int = 100,
+        verify: bool = True,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if api_url is None:
+            api_url = os.environ.get("BGPKIT_BROKER_URL") or DEFAULT_API_URL
+        self.base_url = api_url.rstrip("/")
+        self.page_size = int(page_size)
+        self.verify = verify
+        self.timeout = timeout
+        if not verify:
+            urllib3.disable_warnings()
+
+    def _request(self, endpoint: str, params: Optional[dict] = None) -> dict:
+        """Make a single request and return the parsed JSON body."""
+        return request_json(
+            f"{self.base_url}/{endpoint}",
+            params=params,
+            verify=self.verify,
+            timeout=self.timeout,
+        )
+
+    def _paginate(self, endpoint: str, params: dict) -> dict:
+        """Fetch every page of a paginated broker endpoint.
+
+        Stops when the reported total is reached, or when a page adds no new
+        items. The latter also terminates endpoints that ignore pagination
+        parameters instead of looping on the same full page forever.
+        """
+        page = 1
+        all_data: List[dict] = []
+        seen = set()
+        result = {}
+        while True:
+            page_params = dict(params)
+            page_params["page"] = page
+            page_params["page_size"] = self.page_size
+
+            result = self._request(endpoint, page_params)
+            data = result.get("data", [])
+            new_items = []
+            for item in data:
+                key = json.dumps(item, sort_keys=True, default=str)
+                if key not in seen:
+                    seen.add(key)
+                    new_items.append(item)
+            all_data.extend(new_items)
+
+            total = result.get("total")
+            if not data or not new_items:
+                break
+            if total is not None and len(all_data) >= int(total):
+                break
+            page += 1
+
+        result["data"] = all_data
+        return result
+
+    def query(
+        self,
+        ts_start: str = None,
+        ts_end: str = None,
+        collector_id: str = None,
+        project: str = None,
+        data_type: str = None,
+    ) -> List[BrokerItem]:
+        """Search for MRT data files matching the given criteria."""
+        params = {}
+        if ts_start:
+            params["ts_start"] = ts_start
+        if ts_end:
+            params["ts_end"] = ts_end
+        if collector_id:
+            params["collector_id"] = collector_id
+        if project:
+            check_type(project, str)
+            params["project"] = project
+        if data_type:
+            check_type(data_type, str)
+            params["data_type"] = data_type
+
+        result = self._paginate("search", params)
+        return [from_item(BrokerItem, item) for item in result.get("data", [])]
+
+    def latest(self) -> List[BrokerItem]:
+        """Get the latest MRT data file for every collector and data type."""
+        result = self._request("latest")
+        return [from_item(BrokerItem, item) for item in result.get("data", [])]
+
+    def peers(
+        self,
+        full_feed: bool = None,
+        ip: str = None,
+        asn: int = None,
+        collector: str = None,
+    ) -> List[PeerItem]:
+        """Query BGP peer information."""
+        params = {}
+        if full_feed is not None:
+            params["full_feed"] = str(full_feed).lower()
+        if ip:
+            params["ip"] = ip
+        if asn:
+            params["asn"] = asn
+        if collector:
+            params["collector"] = collector
+
+        result = self._request("peers", params)
+        return [from_item(PeerItem, item) for item in result.get("data", [])]
+
+    def collectors(
+        self,
+        project: str = None,
+        country: str = None,
+        active: bool = None,
+    ) -> List[CollectorItem]:
+        """Query MRT collector information."""
+        params = {}
+        if project:
+            params["project"] = project
+        if country:
+            params["country"] = country
+        if active is not None:
+            params["active"] = str(active).lower()
+
+        result = self._request("collectors", params)
+        return [from_item(CollectorItem, item) for item in result.get("data", [])]

pybgpkit-0.9.0/bgpkit/bgpkit_community.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ._utils import DEFAULT_TIMEOUT, from_item, request_json
+
+
+@dataclass
+class CommunityEntry:
+    asn: int
+    value: str
+    description: str
+    as_name: str = ""
+    country: str = ""
+    source: str = ""
+    range: Optional[str] = None
+
+
+@dataclass
+class CommunitySource:
+    id: str
+    name: str
+    url: str = ""
+    last_updated: Optional[str] = None
+    stats: Optional[dict] = None
+
+
+class CommunityLookup:
+    """BGPKIT community lookup (v3/communities)."""
+
+    def __init__(
+        self,
+        api_url: str = "https://api.bgpkit.com/v3/communities",
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = api_url.rstrip("/")
+        self.timeout = timeout
+
+    def query(
+        self,
+        asn: str = None,
+        value: str = None,
+        description: str = None,
+        as_name: str = None,
+        country: str = None,
+        page: int = 0,
+        page_size: int = 10,
+    ) -> List[CommunityEntry]:
+        """Query BGP communities.
+
+        The API returns one entry per ASN with a nested list of communities;
+        this returns one CommunityEntry per community.
+        """
+        params = {}
+        if asn:
+            params["asn"] = asn
+        if value:
+            params["value"] = value
+        if description:
+            params["description"] = description
+        if as_name:
+            params["as_name"] = as_name
+        if country:
+            params["country"] = country
+        params["page"] = str(page)
+        params["page_size"] = str(min(page_size, 1000))
+
+        response = request_json(self.base_url, params=params, timeout=self.timeout)
+
+        entries = []
+        for item in response.get("data", []):
+            for community in item.get("communities", []) or []:
+                entries.append(
+                    CommunityEntry(
+                        asn=item.get("asn"),
+                        value=community.get("community", ""),
+                        description=community.get("description") or "",
+                        as_name=item.get("name", ""),
+                        country=item.get("country", ""),
+                        source=community.get("source", ""),
+                        range=community.get("range"),
+                    )
+                )
+        return entries
+
+    def sources(self) -> List[CommunitySource]:
+        """List the community data sources."""
+        response = request_json(f"{self.base_url}/sources", timeout=self.timeout)
+        if isinstance(response, list):
+            return [from_item(CommunitySource, item) for item in response]
+        return [from_item(CommunitySource, item) for item in response.get("sources", [])]

pybgpkit-0.9.0/bgpkit/bgpkit_roas.py

@@ -0,0 +1,85 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ._utils import DEFAULT_TIMEOUT, from_item, request_json
+
+DEFAULT_API_URL = "https://api.bgpkit.com/v3/roas"
+
+
+@dataclass
+class RoasItem:
+    prefix: str
+    asn: int
+    max_len: Optional[int] = None
+    tal: Optional[str] = None
+    current: bool = False
+    date_ranges: Optional[List[List[str]]] = None
+
+
+class Roas:
+    """BGPKIT ROAS lookup (v3/roas).
+
+    Queries the ROAS (Route Origin Authorization) database for historical and
+    current RPKI data. The base URL can be overridden per instance with
+    ``api_url``.
+    """
+
+    def __init__(
+        self,
+        api_url: str = DEFAULT_API_URL,
+        page_size: int = 100,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = api_url.rstrip("/")
+        self.page_size = int(page_size)
+        self.timeout = timeout
+
+    def query(
+        self,
+        asn: int = None,
+        prefix: str = None,
+        date: str = None,
+        current: bool = None,
+        page: int = 0,
+        page_size: int = None,
+    ) -> List[RoasItem]:
+        """Query the ROAS database, fetching every page from ``page`` onward.
+
+        Args:
+            asn: AS number to filter by.
+            prefix: IP prefix to filter by.
+            date: Date string (YYYY-MM-DD) for historical lookup.
+            current: If True, return only currently valid ROAs.
+            page: Page number to start from (0-indexed).
+            page_size: Results per page (defaults to the instance page size).
+
+        Returns:
+            List of RoasItem matching the query.
+        """
+        params = {}
+        if asn is not None:
+            params["asn"] = asn
+        if prefix:
+            params["prefix"] = prefix
+        if date:
+            params["date"] = date
+        if current is not None:
+            params["current"] = str(current).lower()
+
+        size = int(page_size) if page_size is not None else self.page_size
+        items: List[RoasItem] = []
+        while True:
+            page_params = dict(params)
+            page_params["page"] = page
+            page_params["page_size"] = size
+            response = request_json(f"{self.base_url}/search", params=page_params, timeout=self.timeout)
+
+            data = response.get("data", [])
+            items.extend(from_item(RoasItem, item) for item in data)
+
+            total = response.get("total")
+            if not data or (total is not None and len(items) >= int(total)):
+                break
+            page += 1
+
+        return items

{pybgpkit-0.8.0 → pybgpkit-0.9.0/pybgpkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybgpkit
-Version: 0.8.0
+Version: 0.9.0
 Summary: BGPKIT tools Python bindings
 Author-email: Mingwei Zhang <mingwei@bgpkit.com>
 License-Expression: MIT

{pybgpkit-0.8.0 → pybgpkit-0.9.0}/pybgpkit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 bgpkit/__init__.py
+bgpkit/_utils.py
 bgpkit/bgpkit_asn.py
 bgpkit/bgpkit_broker.py
 bgpkit/bgpkit_community.py
@@ -13,5 +14,10 @@ pybgpkit.egg-info/SOURCES.txt
 pybgpkit.egg-info/dependency_links.txt
 pybgpkit.egg-info/requires.txt
 pybgpkit.egg-info/top_level.txt
+tests/test_asn_unit.py
+tests/test_broker_unit.py
+tests/test_community_unit.py
 tests/test_integration.py
-tests/test_smoke.py
+tests/test_roas_unit.py
+tests/test_smoke.py
+tests/test_utils_unit.py

{pybgpkit-0.8.0 → pybgpkit-0.9.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pybgpkit"
 dynamic = []
-version = "0.8.0"
+version = "0.9.0"
 description = "BGPKIT tools Python bindings"
 readme = "README.md"
 requires-python = ">=3.9"

pybgpkit-0.9.0/tests/test_asn_unit.py

@@ -0,0 +1,87 @@
+"""Unit tests for AsnLookup, using recorded v3 API response shapes."""
+
+import json
+import unittest
+from unittest import mock
+
+from bgpkit import BGPKITApiError, AsnInfo, AsnLookup
+
+
+class FakeResponse:
+    def __init__(self, payload, status_code=200):
+        self.status_code = status_code
+        self._payload = payload
+        self.text = json.dumps(payload) if payload is not None else ""
+
+    def json(self):
+        if self._payload is None:
+            raise ValueError("body is not JSON")
+        return self._payload
+
+
+def mock_get(response):
+    return mock.patch("bgpkit._utils.requests.get", return_value=response)
+
+
+ASN_PAYLOAD = {
+    "count": 1,
+    "data": [
+        {
+            "as2org": {
+                "country": "US",
+                "name": "GOOGLE",
+                "org_id": "GOGL-ARIN",
+                "org_name": "Google LLC",
+            },
+            "asn": 15169,
+            "country": "US",
+            "country_name": "United States",
+            "hegemony": {"asn": 15169, "ipv4": 0.0079, "ipv6": 0.0027},
+            "name": "GOOGLE - Google LLC",
+            "peeringdb": {"asn": 15169, "name": "Google LLC", "irr_as_set": "RADB::AS-GOOGLE"},
+            "population": {"percent_country": 0, "percent_global": 0, "user_count": 82},
+        }
+    ],
+    "page": 0,
+    "page_size": 1,
+    "pagination": {
+        "page": 0,
+        "page_size": 1,
+        "total_pages": 1,
+        "total_count": 1,
+        "has_next": False,
+        "has_prev": False,
+    },
+    "updatedAt": "2026-10-07T12:00:00",
+}
+
+
+class TestAsnLookup(unittest.TestCase):
+    def test_parses_nested_asn_item(self):
+        with mock_get(FakeResponse(ASN_PAYLOAD)) as get:
+            result = AsnLookup().query(asn="15169")
+        # the v3 ASN endpoint uses a 0-indexed page parameter
+        self.assertEqual(get.call_args.kwargs["params"]["page"], 0)
+        self.assertEqual(result.count, 1)
+        info = result.data[0]
+        self.assertIsInstance(info, AsnInfo)
+        self.assertEqual(info.asn, 15169)
+        self.assertEqual(info.name, "GOOGLE - Google LLC")
+        self.assertEqual(info.country_name, "United States")
+        self.assertEqual(info.org_name, "Google LLC")
+        self.assertEqual(info.org_id, "GOGL-ARIN")
+        self.assertEqual(info.hegemony, {"asn": 15169, "ipv4": 0.0079, "ipv6": 0.0027})
+        self.assertEqual(result.updated_at, "2026-10-07T12:00:00")
+        self.assertIsNotNone(result.pagination)
+        self.assertEqual(result.pagination.total_count, 1)
+        self.assertFalse(result.pagination.has_next)
+
+    def test_raises_on_http_error(self):
+        with mock_get(FakeResponse({"error": "boom"}, status_code=500)):
+            with self.assertRaises(BGPKITApiError) as context:
+                AsnLookup().query(asn="15169")
+        self.assertIn("HTTP 500", str(context.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()