pybgpkit 0.6.2__tar.gz → 0.8.0__tar.gz

pybgpkit-0.8.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: pybgpkit
+Version: 0.8.0
+Summary: BGPKIT tools Python bindings
+Author-email: Mingwei Zhang <mingwei@bgpkit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bgpkit/pybgpkit
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pybgpkit-parser>=0.18.0
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# PyBGPKIT
+
+Python bindings for BGPKIT software. For all software offerings, please check out our GitHub
+repository at <https://github.com/bgpkit>.
+
+## SDKs
+
+### BGPKIT Parser
+
+See the [bgpkit-parser-py documentation](https://github.com/bgpkit/bgpkit-parser-py) for the full API.
+
+```python
+import bgpkit
+
+# Full element parsing
+parser = bgpkit.Parser(url="https://spaces.bgpkit.org/parser/update-example",
+                       filters={"peer_ips": "185.1.8.65, 2001:7f8:73:0:3:fa4:0:1"})
+for elem in parser:
+    print(elem)
+
+# Route-level parsing (faster, fewer fields)
+for route in bgpkit.RouteParser(url="https://spaces.bgpkit.org/parser/update-example"):
+    print(route.prefix, route.as_path)
+
+# Reusable filter objects
+from bgpkit import Filter
+f = Filter.peer_ip("185.1.8.65")
+parser = bgpkit.Parser.from_filters(url, [f])
+```
+
+
+
+### BGPKIT Broker
+
+```python
+import bgpkit
+broker = bgpkit.Broker()
+
+# Search MRT data files
+items = broker.query(ts_start="2024-01-01T00:00:00Z", ts_end="2024-01-01T01:00:00Z")
+print(len(items))
+
+# Get latest files
+latest = broker.latest()
+
+# Query peer information
+peers = broker.peers(asn=13335, full_feed=True)
+
+# List collectors
+collectors = broker.collectors(project="routeviews", active=True)
+```
+
+### BGPKIT IP Lookup
+
+```python
+ip_info = bgpkit.IpLookup().query("1.1.1.1")
+print(ip_info.country, ip_info.as_number, ip_info.as_name)
+```
+
+### BGPKIT ASN Lookup
+
+```python
+result = bgpkit.AsnLookup().query(asn="13335", country="US")
+for asn in result.data:
+    print(asn.asn, asn.name, asn.country)
+```
+
+### BGPKIT Community Lookup
+
+```python
+entries = bgpkit.CommunityLookup().query(asn="13335", page_size=50)
+for entry in entries:
+    print(entry.value, entry.description)
+
+sources = bgpkit.CommunityLookup().sources()
+```
+
+### BGPKIT ROAS Lookup
+
+### BGPKIT ROAS Lookup
+
+```python
+roas = bgpkit.Roas()
+data = roas.query(asn=3333, date="2018-01-01")
+for entry in data:
+    print(entry.prefix, entry.asn, entry.tal)
+
+# Current ROAs only
+current = roas.query(prefix="1.1.1.0/24", current=True)
+```
+
+## Build and Publish
+
+Push a version tag to build and publish automatically via GitHub Actions:
+
+```
+git tag v0.7.0
+git push origin v0.7.0
+```
+
+Manual release:
+
+```
+python -m pip install --upgrade build twine
+python -m build
+twine upload --skip-existing dist/*
+```
+
+PyPI Trusted Publishing is configured for automated releases. See `.github/workflows/release.yml`.
+

pybgpkit-0.8.0/README.md

@@ -0,0 +1,110 @@
+# PyBGPKIT
+
+Python bindings for BGPKIT software. For all software offerings, please check out our GitHub
+repository at <https://github.com/bgpkit>.
+
+## SDKs
+
+### BGPKIT Parser
+
+See the [bgpkit-parser-py documentation](https://github.com/bgpkit/bgpkit-parser-py) for the full API.
+
+```python
+import bgpkit
+
+# Full element parsing
+parser = bgpkit.Parser(url="https://spaces.bgpkit.org/parser/update-example",
+                       filters={"peer_ips": "185.1.8.65, 2001:7f8:73:0:3:fa4:0:1"})
+for elem in parser:
+    print(elem)
+
+# Route-level parsing (faster, fewer fields)
+for route in bgpkit.RouteParser(url="https://spaces.bgpkit.org/parser/update-example"):
+    print(route.prefix, route.as_path)
+
+# Reusable filter objects
+from bgpkit import Filter
+f = Filter.peer_ip("185.1.8.65")
+parser = bgpkit.Parser.from_filters(url, [f])
+```
+
+
+
+### BGPKIT Broker
+
+```python
+import bgpkit
+broker = bgpkit.Broker()
+
+# Search MRT data files
+items = broker.query(ts_start="2024-01-01T00:00:00Z", ts_end="2024-01-01T01:00:00Z")
+print(len(items))
+
+# Get latest files
+latest = broker.latest()
+
+# Query peer information
+peers = broker.peers(asn=13335, full_feed=True)
+
+# List collectors
+collectors = broker.collectors(project="routeviews", active=True)
+```
+
+### BGPKIT IP Lookup
+
+```python
+ip_info = bgpkit.IpLookup().query("1.1.1.1")
+print(ip_info.country, ip_info.as_number, ip_info.as_name)
+```
+
+### BGPKIT ASN Lookup
+
+```python
+result = bgpkit.AsnLookup().query(asn="13335", country="US")
+for asn in result.data:
+    print(asn.asn, asn.name, asn.country)
+```
+
+### BGPKIT Community Lookup
+
+```python
+entries = bgpkit.CommunityLookup().query(asn="13335", page_size=50)
+for entry in entries:
+    print(entry.value, entry.description)
+
+sources = bgpkit.CommunityLookup().sources()
+```
+
+### BGPKIT ROAS Lookup
+
+### BGPKIT ROAS Lookup
+
+```python
+roas = bgpkit.Roas()
+data = roas.query(asn=3333, date="2018-01-01")
+for entry in data:
+    print(entry.prefix, entry.asn, entry.tal)
+
+# Current ROAs only
+current = roas.query(prefix="1.1.1.0/24", current=True)
+```
+
+## Build and Publish
+
+Push a version tag to build and publish automatically via GitHub Actions:
+
+```
+git tag v0.7.0
+git push origin v0.7.0
+```
+
+Manual release:
+
+```
+python -m pip install --upgrade build twine
+python -m build
+twine upload --skip-existing dist/*
+```
+
+PyPI Trusted Publishing is configured for automated releases. See `.github/workflows/release.yml`.
+

pybgpkit-0.8.0/bgpkit/__init__.py

@@ -0,0 +1,6 @@
+from .bgpkit_parser import Filter, Parser, RouteElem, RouteParser
+from .bgpkit_broker import Broker, BrokerItem, CollectorItem, PeerItem
+from .bgpkit_roas import Roas, RoasItem
+from .bgpkit_ip import IpLookup, IpInfo
+from .bgpkit_asn import AsnLookup, AsnInfo, AsnLookupResult
+from .bgpkit_community import CommunityLookup, CommunityEntry, CommunitySource

pybgpkit-0.8.0/bgpkit/bgpkit_asn.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+import requests
+
+
+@dataclass
+class Pagination:
+    next: Optional[str] = None
+    previous: Optional[str] = None
+
+
+@dataclass
+class AsnInfo:
+    asn: int
+    name: str
+    country: str = ""
+    org_name: str = ""
+    org_id: str = ""
+    description: str = ""
+    website: str = ""
+
+
+@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"):
+        self.base_url = api_url.rstrip("/")
+
+    def query(
+        self,
+        asn: str = None,
+        country: str = None,
+        search: str = None,
+        page: int = 1,
+        page_size: int = 100,
+    ) -> AsnLookupResult:
+        params = {}
+        if asn:
+            params["asn"] = asn
+        if country:
+            params["country"] = country
+        if search:
+            params["search"] = search
+        if page:
+            params["page"] = page
+        if page_size:
+            params["page_size"] = min(page_size, 10000)
+
+        res = requests.get(f"{self.base_url}/asn", params=params).json()
+        data = [AsnInfo(**item) for item in res.get("data", [])]
+        pag = res.get("pagination", {})
+        return AsnLookupResult(
+            data=data,
+            count=res.get("count", 0),
+            page=res.get("page", page),
+            page_size=res.get("page_size", page_size),
+            updated_at=res.get("updatedAt", ""),
+            pagination=Pagination(**pag) if pag else None,
+        )

pybgpkit-0.8.0/bgpkit/bgpkit_broker.py

@@ -0,0 +1,176 @@
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import requests as requests
+import urllib3
+
+
+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
+
+
+@dataclass
+class PeerItem:
+    ip: str
+    asn: int
+    collector: str
+    full_feed: bool = False
+
+
+@dataclass
+class CollectorItem:
+    id: str
+    name: str
+    project: str
+    country: str
+    active: bool = True
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+
+
+@dataclass
+class LatestResult:
+    """Result of the /v3/broker/latest endpoint."""
+    items: List[BrokerItem] = field(default_factory=list)
+
+
+class Broker:
+    """BGPKIT Broker v3 API wrapper.
+
+    Provides access to MRT data file search, peer information,
+    collector metadata, and latest file discovery.
+    """
+
+    def __init__(
+        self,
+        api_url: str = "https://api.bgpkit.com/v3/broker",
+        page_size: int = 100,
+        verify: bool = True,
+    ):
+        self.base_url = api_url.rstrip("/")
+        self.page_size = int(page_size)
+        self.verify = verify
+        if not verify:
+            urllib3.disable_warnings()
+
+    def _paginate(self, endpoint: str, params: dict) -> dict:
+        """Fetch all pages of a paginated broker endpoint."""
+        page = 1
+        all_data = []
+
+        while True:
+            params["page"] = page
+            params["page_size"] = self.page_size
+            res = requests.get(
+                f"{self.base_url}/{endpoint}",
+                params=params,
+                verify=self.verify,
+            ).json()
+
+            if isinstance(res, dict):
+                data = res.get("data", [])
+                all_data.extend(data)
+                if len(data) < self.page_size:
+                    break
+            elif isinstance(res, list):
+                all_data.extend(res)
+                break
+            else:
+                break
+
+            page += 1
+
+        result = res if isinstance(res, dict) else {"data": all_data}
+        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 [BrokerItem(**item) for item in result.get("data", [])]
+
+    def latest(self) -> List[BrokerItem]:
+        """Get latest MRT data files across projects."""
+        res = requests.get(
+            f"{self.base_url}/latest",
+            verify=self.verify,
+        ).json()
+        if isinstance(res, list):
+            return [BrokerItem(**item) for item in res]
+        data = res.get("data", [])
+        return [BrokerItem(**item) for item in 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._paginate("peers", params)
+        return [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._paginate("collectors", params)
+        return [CollectorItem(**item) for item in result.get("data", [])]

pybgpkit-0.8.0/bgpkit/bgpkit_community.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+import requests
+
+
+@dataclass
+class CommunityEntry:
+    asn: int
+    value: str
+    description: str
+    as_name: str = ""
+    country: str = ""
+    source: str = ""
+
+
+@dataclass
+class CommunitySource:
+    id: str
+    name: str
+    url: str = ""
+
+
+class CommunityLookup:
+    """BGPKIT community lookup (v3/communities)."""
+
+    def __init__(self, api_url: str = "https://api.bgpkit.com/v3/communities"):
+        self.base_url = api_url.rstrip("/")
+
+    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]:
+        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))
+
+        res = requests.get(self.base_url, params=params).json()
+        if isinstance(res, list):
+            return [CommunityEntry(**item) for item in res]
+        return [CommunityEntry(**item) for item in res.get("data", [])]
+
+    def sources(self) -> List[CommunitySource]:
+        res = requests.get(f"{self.base_url}/sources").json()
+        if isinstance(res, list):
+            return [CommunitySource(**item) for item in res]
+        return [CommunitySource(**item) for item in res.get("data", [])]

pybgpkit-0.8.0/bgpkit/bgpkit_ip.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+
+@dataclass
+class AsnDetail:
+    asn: int
+    name: str
+    country: str
+    org_name: str = ""
+    org_id: str = ""
+
+
+@dataclass
+class IpInfo:
+    ip: str
+    country: str
+    asn: Optional[dict] = None
+
+    @property
+    def as_number(self) -> Optional[int]:
+        if self.asn:
+            return self.asn.get("asn")
+        return None
+
+    @property
+    def as_name(self) -> Optional[str]:
+        if self.asn:
+            return self.asn.get("name")
+        return None
+
+
+class IpLookup:
+    """BGPKIT IP address lookup (v3/utils/ip)."""
+
+    def __init__(self, api_url: str = "https://api.bgpkit.com/v3/utils"):
+        self.base_url = api_url.rstrip("/")
+
+    def query(self, ip: str = None, simple: bool = False) -> IpInfo:
+        params = {}
+        if ip:
+            params["ip"] = ip
+        if simple:
+            params["simple"] = "true"
+
+        res = requests.get(f"{self.base_url}/ip", params=params).json()
+        return IpInfo(**res)

pybgpkit-0.8.0/bgpkit/bgpkit_parser.py

@@ -0,0 +1,3 @@
+from pybgpkit_parser import Filter, Parser, RouteElem, RouteParser
+
+__all__ = ["Parser", "RouteParser", "RouteElem", "Filter"]

pybgpkit-0.8.0/bgpkit/bgpkit_roas.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+import requests
+
+
+@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 (alpha API).
+
+    Queries the ROAS (Route Origination Authorization) database
+    for historical and current RPKI data.
+    """
+
+    def __init__(self, api_url: str = "https://alpha.api.bgpkit.com"):
+        self.base_url = api_url.rstrip("/")
+
+    def query(
+        self,
+        asn: int = None,
+        prefix: str = None,
+        date: str = None,
+        current: bool = None,
+        page: int = 1,
+        page_size: int = None,
+    ) -> List[RoasItem]:
+        """Query ROAS database.
+
+        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 (1-indexed).
+            page_size: Results per page. Defaults to 5 (alpha API limitation).
+
+        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()
+        params["page"] = str(page)
+        params["page_size"] = str(page_size if page_size is not None else 5)
+
+        res = requests.get(f"{self.base_url}/roas", params=params).json()
+        if isinstance(res, list):
+            return [RoasItem(**item) for item in res]
+        return [RoasItem(**item) for item in res.get("data", [])]