### Install pybgpkit via pip

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/README.md

Standard installation command for the pybgpkit package.

```bash
pip install pybgpkit
```

--------------------------------

### Parse data with filters

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Example of initializing a parser with specific filters and iterating through the results.

```python
import bgpkit

parser = bgpkit.Parser(
    url="https://spaces.bgpkit.org/parser/update-example",
    filters={
        "peer_ips": "185.1.8.65",
        "prefixes": "1.1.1.0/24"
    }
)
for elem in parser:
    print(elem)
```

--------------------------------

### Manual Python Package Release

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Manually builds and uploads a Python package to PyPI using the `build` and `twine` tools. Ensure these are installed before running.

```bash
python -m pip install --upgrade build twine
python -m build
twine upload --skip-existing dist/*
```

--------------------------------

### Get Latest BGP Data Files with Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Retrieves the latest available MRT data files using the BGPKIT Broker. This is useful for accessing the most recent BGP information.

```python
# Get latest files
latest = broker.latest()
```

--------------------------------

### AsnLookup.__init__

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-asn.md

Initializes the AsnLookup client with an optional base API URL.

```APIDOC
## AsnLookup.__init__(api_url: str = "https://api.bgpkit.com/v3/utils")

### Description
Initializes a new instance of the AsnLookup client. This client is used to perform queries against the BGPKIT v3 utilities API.

### Parameters
- **api_url** (str) - Optional - The base URL for the BGPKIT v3 utilities API endpoint. Defaults to "https://api.bgpkit.com/v3/utils".
```

--------------------------------

### Initialize RouteParser and Iterate Routes

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Demonstrates creating a RouteParser instance and iterating through parsed route elements to access prefix and AS path information.

```python
import bgpkit

# Fast route-level parsing
parser = bgpkit.RouteParser(url="https://spaces.bgpkit.org/parser/update-example")

for route in parser:
    print(f"{route.prefix} -> {route.as_path}")
```

--------------------------------

### Initialize AsnLookup client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-asn.md

Instantiate the client using the default API endpoint or a custom URL.

```python
import bgpkit

# Create with default API endpoint
asn_lookup = bgpkit.AsnLookup()

# Custom API endpoint
asn_lookup = bgpkit.AsnLookup(api_url="https://custom.api.example.com/v3/utils")
```

--------------------------------

### Initialize Broker Client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-broker.md

Instantiate the Broker client with custom API endpoints, pagination settings, or SSL verification options.

```python
import bgpkit

# Create a broker client with default settings
broker = bgpkit.Broker()

# Custom API endpoint and increased page size
broker = bgpkit.Broker(
    api_url="https://custom.api.example.com/v3/broker",
    page_size=500
)

# Disable SSL verification (not recommended for production)
broker = bgpkit.Broker(verify=False)
```

--------------------------------

### Roas.__init__

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Initializes the BGPKIT ROAs client with an optional custom API base URL.

```APIDOC
## Roas.__init__(api_url: str = "https://alpha.api.bgpkit.com")

### Description
Initializes the client used to query the RPKI ROAs database.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT alpha API endpoint. Defaults to "https://alpha.api.bgpkit.com".
```

--------------------------------

### Initialize Roas client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Instantiate the Roas class with a custom API URL.

```python
roas = bgpkit.Roas(
    api_url="https://alpha.api.bgpkit.com"
)
```

--------------------------------

### Initialize Parser client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Instantiate the Parser class with a data URL and optional filters.

```python
parser = bgpkit.Parser(
    url="https://spaces.bgpkit.org/parser/update-example",
    filters={"peer_ips": "185.1.8.65", "prefixes": "1.0.0.0/8"}
)
```

--------------------------------

### IpLookup.__init__

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Initializes the IpLookup client with an optional custom API URL.

```APIDOC
## Constructor: IpLookup.__init__

### Description
Initializes the client used for looking up IP address information. The default API endpoint is set to the BGPKIT v3 utilities service.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT v3 utilities API endpoint. Defaults to "https://api.bgpkit.com/v3/utils".
```

--------------------------------

### Broker.__init__

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-broker.md

Initializes the BGPKIT Broker client to interact with the BGPKIT Broker v3 API.

```APIDOC
## Constructor: Broker.__init__

### Description
Initializes a new instance of the Broker client. This client acts as a wrapper around the BGPKIT Broker v3 HTTP API.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT Broker API v3 endpoint. Defaults to "https://api.bgpkit.com/v3/broker".
- **page_size** (int) - Optional - Number of results per page for paginated endpoints. Defaults to 100.
- **verify** (bool) - Optional - Whether to verify SSL certificates for HTTPS requests. Defaults to True.
```

--------------------------------

### Configure BGPKIT services

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Instantiate Broker and Parser services with custom parameters and filters.

```python
# Broker with custom endpoint
broker = bgpkit.Broker(
    api_url="https://custom.api.example.com/v3/broker",
    page_size=500,
    verify=False  # Disable SSL (dev only)
)

# Parser with filters
parser = bgpkit.Parser(
    url="https://example.com/data.mrt",
    filters={"peer_ips": "192.0.2.1", "prefixes": "1.0.0.0/8"}
)
```

--------------------------------

### Initialize BGPKIT Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Configures the Broker client with custom API URL, page size, and SSL verification settings.

```python
broker = bgpkit.Broker(
    api_url="https://api.bgpkit.com/v3/broker",
    page_size=100,
    verify=True
)
```

--------------------------------

### Initialize Roas Client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Instantiate the Roas client using either the default BGPKIT alpha API endpoint or a custom URL.

```python
import bgpkit

# Create with default API endpoint
roas = bgpkit.Roas()

# Custom API endpoint
roas = bgpkit.Roas(api_url="https://custom.api.example.com")
```

--------------------------------

### Initialize Parser with URL and Filters

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Constructs a Parser instance to iterate over BGP route elements from a specified URL with optional peer IP filtering.

```python
import bgpkit

# Parse a BGP update file with peer filtering
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"}
)

# Iterate over parsed elements
for elem in parser:
    print(f"{elem.prefix} from AS{elem.peer_asn}")
```

--------------------------------

### Discover Available Sources

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Lists all available community databases supported by the lookup tool.

```python
# See what community databases are available
sources = community_lookup.sources()
for source in sources:
    print(f"Source: {source.name} ({source.id})")
    print(f"  Reference: {source.url}")
```

--------------------------------

### Importing BGPKIT components

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/module-overview.md

Demonstrates various ways to import BGPKIT classes, ranging from top-level package access to specific submodule and selective imports.

```python
import bgpkit
broker = bgpkit.Broker()
```

```python
from bgpkit.bgpkit_broker import Broker
from bgpkit.bgpkit_parser import Parser
```

```python
from bgpkit import Parser, Filter, Broker, IpLookup, AsnLookup, CommunityLookup, Roas
```

--------------------------------

### CommunityLookup.__init__

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Initializes the CommunityLookup client with an optional custom API URL.

```APIDOC
## Constructor: CommunityLookup.__init__

### Description
Initializes the client for querying BGP community definitions. The default API URL points to the official BGPKIT community endpoint.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT communities API endpoint. Defaults to "https://api.bgpkit.com/v3/communities".
```

--------------------------------

### bgpkit.Roas Constructor

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Initializes the Roas client for interacting with the BGPKIT alpha API.

```APIDOC
## bgpkit.Roas(api_url)

### Description
Initializes the ROAs client to query BGPKIT alpha API data.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT alpha API. Defaults to "https://alpha.api.bgpkit.com".
```

--------------------------------

### bgpkit.Parser Constructor

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Initializes the MRT data parser.

```APIDOC
## bgpkit.Parser(url, filters)

### Description
Initializes the parser to process MRT data from a specified URL or file path.

### Parameters
- **url** (str) - Required - URL to MRT data file (http, https, file, or local path).
- **filters** (Dict[str, str]) - Optional - Dictionary of filter criteria (peer_ips, peer_asns, prefixes, prefix_ranges, communities).
```

--------------------------------

### Initialize AsnLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Constructor for the AsnLookup class, allowing customization of the API base URL.

```python
asn_lookup = bgpkit.AsnLookup(
    api_url="https://api.bgpkit.com/v3/utils"
)
```

--------------------------------

### Initialize IpLookup Client

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Instantiate the client with either the default BGPKIT API endpoint or a custom URL.

```python
import bgpkit

# Create with default API endpoint
ip_lookup = bgpkit.IpLookup()

# Custom API endpoint
ip_lookup = bgpkit.IpLookup(api_url="https://custom.api.example.com/v3/utils")
```

--------------------------------

### Execute Multi-Service BGP Workflow

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Demonstrates a complete workflow: finding BGP data files, parsing them for specific prefixes, and enriching results with ASN information.

```python
import bgpkit

# 1. Find recent BGP data
broker = bgpkit.Broker()
items = broker.query(
    ts_start="2024-01-01T00:00:00Z",
    ts_end="2024-01-01T01:00:00Z",
    data_type="update"
)
print(f"Found {len(items)} update files")

# 2. Parse first file
if items:
    url = items[0].url
    parser = bgpkit.Parser(url=url, filters={"prefixes": "1.0.0.0/8"})
    elements = parser.parse_all()
    print(f"Parsed {len(elements)} matching prefixes")
    
    # 3. Lookup AS information
    asn_lookup = bgpkit.AsnLookup()
    asn_info = {}
    for elem in elements[:5]:
        asn = elem.peer_asn
        if asn not in asn_info:
            result = asn_lookup.query(asn=str(asn))
            if result.data:
                asn_info[asn] = result.data[0].name
    
    # 4. Print enriched data
    for asn, name in asn_info.items():
        print(f"  AS{asn}: {name}")
```

--------------------------------

### Complete IP Lookup Usage

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Demonstrates standard lookup workflows and basic error handling for invalid inputs.

```python
import bgpkit

ip_lookup = bgpkit.IpLookup()

# Lookup Cloudflare's IP
cloudflare = ip_lookup.query(ip="1.1.1.1")
print(f"IP {cloudflare.ip} is in {cloudflare.country}")
print(f"Belongs to AS{cloudflare.as_number} ({cloudflare.as_name})")

# Lookup Google's public DNS
google = ip_lookup.query(ip="8.8.8.8")
print(f"Country: {google.country}, AS: {google.as_number}")

# Error handling
try:
    result = ip_lookup.query(ip="invalid")
except Exception as e:
    print(f"Lookup failed: {e}")
```

--------------------------------

### Initialize CommunityLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Instantiate the client using the default API endpoint or a custom URL.

```python
import bgpkit

# Create with default API endpoint
community_lookup = bgpkit.CommunityLookup()

# Custom API endpoint
community_lookup = bgpkit.CommunityLookup(
    api_url="https://custom.api.example.com/v3/communities"
)
```

--------------------------------

### Import BGPKIT types

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Import necessary service classes, data types, and utilities from the top-level package.

```python
from bgpkit import (
    # Service classes
    Broker, IpLookup, AsnLookup, CommunityLookup, Roas,
    Parser, RouteParser,
    
    # Data types
    BrokerItem, PeerItem, CollectorItem,
    IpInfo, AsnInfo, AsnLookupResult,
    CommunityEntry, CommunitySource,
    RoasItem, RouteElem,
    
    # Utilities
    Filter,
)
```

--------------------------------

### Configure Custom Broker Endpoint

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Initializes a Broker instance with a custom API URL and disables SSL verification for internal testing.

```python
import bgpkit

broker = bgpkit.Broker(
    api_url="https://internal.company.com/bgpkit/broker",
    page_size=500,
    verify=False  # For internal/testing only
)

items = broker.query(
    ts_start="2024-01-01T00:00:00Z",
    ts_end="2024-01-01T01:00:00Z"
)
```

--------------------------------

### Perform Basic ASN Lookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-asn.md

Initializes the AsnLookup client and retrieves details for a specific ASN.

```python
import bgpkit

asn_lookup = bgpkit.AsnLookup()

# Get details for a specific AS
result = asn_lookup.query(asn="15169")  # Google
if result.data:
    info = result.data[0]
    print(f"AS{info.asn}: {info.name}")
    print(f"Country: {info.country}")
    print(f"Website: {info.website}")
    print(f"Description: {info.description}")
```

--------------------------------

### Build and Push Git Tag for Release

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Tags a new version and pushes it to the origin repository to trigger automated builds and releases via GitHub Actions.

```bash
git tag v0.7.0
git push origin v0.7.0
```

--------------------------------

### Handle RequestException in BGPKIT

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Demonstrates catching network-related exceptions when querying the BGPKIT broker.

```python
import bgpkit
from requests.exceptions import RequestException

broker = bgpkit.Broker()

try:
    items = broker.query(ts_start="2024-01-01T00:00:00Z")
except RequestException as e:
    print(f"Network error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### View project source code organization

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Displays the directory structure of the pybgpkit repository.

```text
bgpkit/
├── __init__.py                 # Top-level exports
├── bgpkit_parser.py            # Parser module (re-exports)
├── bgpkit_broker.py            # Broker API client
├── bgpkit_ip.py                # IP Lookup API client
├── bgpkit_asn.py               # ASN Lookup API client
├── bgpkit_community.py         # Community Lookup API client
└── bgpkit_roas.py              # ROAs API client
```

--------------------------------

### bgpkit.Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Configuration options for the Broker class constructor.

```APIDOC
## bgpkit.Broker

### Description
Initializes the Broker client for interacting with the BGPKIT Broker v3 API.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT Broker v3 API. Default: "https://api.bgpkit.com/v3/broker"
- **page_size** (int) - Optional - Number of results per page for paginated endpoints. Default: 100
- **verify** (bool) - Optional - SSL certificate verification for HTTPS requests. Default: True
```

--------------------------------

### Query ROAs by Prefix

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Lookup authorization details for a specific IP prefix.

```python
# Lookup authorization for a specific prefix
result = roas.query(prefix="1.1.1.0/24")
if result:
    roa = result[0]
    print(f"Prefix {roa.prefix} is authorized for:")
    print(f"  AS{roa.asn}")
    if roa.max_len:
        print(f"  Max length: /{roa.max_len}")
else:
    print("Prefix not found in ROAS database")
```

--------------------------------

### List Community Sources

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Retrieve a list of all available BGP community source databases.

```python
import bgpkit

community_lookup = bgpkit.CommunityLookup()

# Get available sources
sources = community_lookup.sources()
for source in sources:
    print(f"{source.id}: {source.name}")
    if source.url:
        print(f"  URL: {source.url}")
```

--------------------------------

### Discover Community Databases

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Lists available community source databases and their metadata.

```python
import bgpkit

community_lookup = bgpkit.CommunityLookup()

# List available source databases
sources = community_lookup.sources()
for source in sources:
    print(f"{source.name} ({source.id})")
    if source.url:
        print(f"  {source.url}")
```

--------------------------------

### BGP Parsing with Reusable Filters

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Demonstrates creating and using reusable filter objects, such as peer IP filters, with the BGPKIT Parser. This allows for more modular filter management.

```python
# Reusable filter objects
from bgpkit import Filter
f = Filter.peer_ip("185.1.8.65")
parser = bgpkit.Parser.from_filters(url, [f])
```

--------------------------------

### Perform BGP data discovery, parsing, and ASN lookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/README.md

Demonstrates the workflow of querying MRT data files, parsing BGP updates, and performing ASN lookups using the pybgpkit library.

```python
import bgpkit

# Find MRT data
broker = bgpkit.Broker()
files = broker.query(ts_start="2024-01-01T00:00:00Z", ts_end="2024-01-01T01:00:00Z")

# Parse BGP updates
parser = bgpkit.Parser(url=files[0].url)
elements = parser.parse_all()

# Lookup AS information
asn_lookup = bgpkit.AsnLookup()
for elem in elements[:5]:
    result = asn_lookup.query(asn=str(elem.peer_asn))
    if result.data:
        print(f"AS{elem.peer_asn}: {result.data[0].name}")
```

--------------------------------

### RouteParser Constructor

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Initializes a new RouteParser instance to iterate over MRT data files.

```APIDOC
## RouteParser(url: str, **kwargs)

### Description
Initializes a lightweight parser for MRT data files, optimized for per-route metrics.

### Parameters
- **url** (str) - Required - URL to the MRT data file.

### Returns
- **RouteParser** - An iterator over RouteElem objects.
```

--------------------------------

### bgpkit.IpLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Configuration options for the IpLookup class constructor.

```APIDOC
## bgpkit.IpLookup

### Description
Initializes the IpLookup client for interacting with the BGPKIT v3 utilities API.

### Parameters
- **api_url** (str) - Optional - Base URL for the BGPKIT v3 utilities API. Default: "https://api.bgpkit.com/v3/utils"
```

--------------------------------

### bgpkit.AsnLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Constructor and query method for ASN lookup operations.

```APIDOC
## bgpkit.AsnLookup

### Constructor
`bgpkit.AsnLookup(api_url="https://api.bgpkit.com/v3/utils")`

- **api_url** (str) - Optional - Base URL for the BGPKIT v3 utilities API.

### Method: query()
Queries the ASN database with optional filters.

#### Parameters
- **asn** (str) - Optional - Filter by AS number.
- **country** (str) - Optional - Filter by 2-letter country code.
- **search** (str) - Optional - Free-text search in AS name/organization.
- **page** (int) - Optional - Page number (1-indexed).
- **page_size** (int) - Optional - Results per page (1-10000).
```

--------------------------------

### List Active Collectors with Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Lists active collectors for a given project using the BGPKIT Broker. This helps in identifying available data sources.

```python
# List collectors
collectors = broker.collectors(project="routeviews", active=True)
```

--------------------------------

### Create Parser with Filter Objects

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Initializes a Parser using a list of Filter objects for more granular control over the data being parsed.

```python
from bgpkit import Parser, Filter

# Create filters
peer_filter = Filter.peer_ip("185.1.8.65")
prefix_filter = Filter.prefix_range("1.0.0.0/8")

# Parse with multiple filters
parser = Parser.from_filters(
    url="https://spaces.bgpkit.org/parser/update-example",
    filters=[peer_filter, prefix_filter]
)

for elem in parser:
    print(elem)
```

--------------------------------

### Enable Request Logging

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Configures the logging module to output debug information for requests and urllib3, useful for tracing network activity.

```python
import logging
import requests

logging.basicConfig()
logging.getLogger("requests").setLevel(logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)

# Now all requests will be logged
broker = bgpkit.Broker()
items = broker.query(ts_start="2024-01-01T00:00:00Z")
```

--------------------------------

### Implement retry logic for Broker queries

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Demonstrates a robust pattern for handling RequestException during API calls by implementing a retry loop with a specified delay.

```python
import bgpkit
from requests.exceptions import RequestException
import time

broker = bgpkit.Broker()
max_retries = 3
retry_delay = 2

for attempt in range(max_retries):
    try:
        items = broker.query(
            ts_start="2024-01-01T00:00:00Z",
            ts_end="2024-01-01T01:00:00Z"
        )
        break  # Success
    except RequestException as e:
        if attempt < max_retries - 1:
            print(f"Attempt {attempt + 1} failed, retrying...")
            time.sleep(retry_delay)
        else:
            print("All retries exhausted")
            raise
```

--------------------------------

### Parser Constructor

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Initializes a new Parser instance to process MRT data files from a URL or local path, with optional filtering criteria.

```APIDOC
## Parser(url: str, filters: Dict[str, str] = None, **kwargs)

### Description
Initializes a parser for BGP UPDATE messages and RIB dumps. The parser acts as an iterator over RouteElem objects.

### Parameters
- **url** (str) - Required - URL to MRT data file (http, https, file, or local path).
- **filters** (Dict[str, str]) - Optional - Dictionary of filter criteria (e.g., peer_ips, peer_asns, prefixes, communities).

### Returns
- **Parser** - An iterator over RouteElem objects.
```

--------------------------------

### Check RPKI coverage

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Verify RPKI ROA status for a specific prefix.

```python
roas = bgpkit.Roas()
result = roas.query(prefix="1.1.1.0/24")
for roa in result:
    print(f"{roa.prefix} -> AS{roa.asn}")
```

--------------------------------

### Query AS information

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-asn.md

Perform lookups by ASN, country, or organization name, with support for pagination.

```python
import bgpkit

asn_lookup = bgpkit.AsnLookup()

# Query specific AS number
result = asn_lookup.query(asn="13335")
print(f"AS13335: {result.data[0].name if result.data else 'Not found'}")
for asn_info in result.data:
    print(f"  {asn_info.asn}: {asn_info.name} ({asn_info.country})")

# Search by country
us_asns = asn_lookup.query(country="US", page_size=50)
print(f"Found {us_asns.count} US ASs (showing {len(us_asns.data)})")

# Free-text search
google_asns = asn_lookup.query(search="Google", page_size=10)
for asn in google_asns.data:
    print(f"AS{asn.asn}: {asn.name}")

# Pagination
result = asn_lookup.query(country="NL", page=2, page_size=25)
print(f"Page {result.page} of results (page_size={result.page_size})")
if result.pagination and result.pagination.next:
    print(f"Next page: {result.pagination.next}")
```

--------------------------------

### Find AS information

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Retrieve ASN details using the AsnLookup service.

```python
asn_lookup = bgpkit.AsnLookup()
result = asn_lookup.query(asn="15169")
for asn_info in result.data:
    print(f"AS{asn_info.asn}: {asn_info.name}")
```

--------------------------------

### Initialize CommunityLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Constructor for the CommunityLookup class, allowing customization of the API base URL.

```python
community_lookup = bgpkit.CommunityLookup(
    api_url="https://api.bgpkit.com/v3/communities"
)
```

--------------------------------

### Implementing Exponential Backoff Retry Logic

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Wrap broker queries in a retry loop with exponential backoff to handle transient network failures gracefully.

```python
import time
from requests.exceptions import RequestException

def query_with_retry(broker, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return broker.query(**kwargs)
        except RequestException as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Retry in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
```

--------------------------------

### Validate Prefixes with RPKI

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Queries ROA data to check if a specific prefix is authorized for an AS.

```python
import bgpkit

roas = bgpkit.Roas()

# Check if a prefix is covered by RPKI
result = roas.query(prefix="1.1.1.0/24")
if result:
    roa = result[0]
    print(f"Prefix {roa.prefix} is authorized for AS{roa.asn}")
    if roa.max_len:
        print(f"  Max allowed length: /{roa.max_len}")
```

--------------------------------

### Cap page_size for AsnLookup.query

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Limits the page_size parameter to a maximum of 10,000 to comply with API constraints.

```python
if page_size:
    params["page_size"] = min(page_size, 10000)
```

--------------------------------

### Set default page_size for Roas.query

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Sets a default page_size of 5 if no value is provided.

```python
params["page_size"] = str(page_size if page_size is not None else 5)
```

--------------------------------

### Search Communities by Description

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Performs a keyword search across community descriptions.

```python
# Find communities related to peering
peering_communities = community_lookup.query(
    description="peering",
    page_size=50
)
for entry in peering_communities:
    print(f"AS{entry.asn} ({entry.as_name}): {entry.value}")
    print(f"  {entry.description}")
```

--------------------------------

### Search BGP Communities by Keyword

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Searches for BGP communities based on their description field.

```python
import bgpkit

community_lookup = bgpkit.CommunityLookup()

# Find communities related to traffic policies
traffic = community_lookup.query(description="traffic", page_size=50)
print(f"Found {len(traffic)} traffic-related communities")

# Show unique operators
operators = set(e.as_name for e in traffic if e.as_name)
print(f"Defined by {len(operators)} operators")
```

--------------------------------

### Look up IP information

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/INDEX.md

Query IP address details using the IpLookup service.

```python
ip_lookup = bgpkit.IpLookup()
result = ip_lookup.query(ip="1.1.1.1")
print(result.country, result.as_number)
```

--------------------------------

### bgpkit.RouteParser

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

A specialized, memory-efficient parser optimized for route-level data extraction.

```APIDOC
## bgpkit.RouteParser

### Description
Optimized parser for extracting route-level information from MRT files with minimal memory footprint.

### Constructor
`bgpkit.RouteParser(url: str)`

### Parameters
- **url** (str) - Required - The location of the MRT file.

### Methods
- **count()** - Returns the total number of routes in the file.
- **__iter__()** - Allows streaming iteration over route objects.
```

--------------------------------

### Importing core classes from the bgpkit package

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/module-overview.md

The top-level bgpkit module re-exports public classes and functions for parsers, broker APIs, and lookup services.

```python
from bgpkit import (
    # Parser (from pybgpkit_parser dependency)
    Parser, RouteParser, RouteElem, Filter,
    
    # Broker API
    Broker, BrokerItem, CollectorItem, PeerItem,
    
    # IP Lookup API
    IpLookup, IpInfo,
    
    # ASN Lookup API
    AsnLookup, AsnInfo, AsnLookupResult,
    
    # Community Lookup API
    CommunityLookup, CommunityEntry, CommunitySource,
    
    # RPKI/ROAs API
    Roas, RoasItem,
)
```

--------------------------------

### CommunityLookup.sources

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Retrieves a list of all available BGP community source databases.

```APIDOC
## Method: CommunityLookup.sources

### Description
Lists all available BGP community source databases available through the API.

### Returns
- **List[CommunitySource]** - List of community source databases.
```

--------------------------------

### Handling Empty Query Results

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Check if the returned list is empty before iterating to avoid errors when no data matches the query criteria.

```python
broker = bgpkit.Broker()
items = broker.query(ts_start="2099-01-01T00:00:00Z")  # Future date

if not items:
    print("No results found")
else:
    for item in items:
        print(item.url)
```

--------------------------------

### bgpkit.Roas.query()

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Queries ROA data with optional filters.

```APIDOC
## Roas.query(asn, prefix, date, current, page, page_size)

### Description
Queries historical or current ROA data based on provided filters.

### Parameters
- **asn** (int) - Optional - Filter by authorizing AS number.
- **prefix** (str) - Optional - Filter by IP prefix (e.g., "1.1.1.0/24").
- **date** (str) - Optional - Query historical ROAs at a specific date (YYYY-MM-DD).
- **current** (bool) - Optional - Filter by validity: True for valid, False for withdrawn.
- **page** (int) - Optional - Page number (1-indexed). Defaults to 1.
- **page_size** (int) - Optional - Results per page. Defaults to 5.
```

--------------------------------

### Inspect API Responses Manually

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Demonstrates how to perform a manual request using the requests library to inspect status codes, headers, and response bodies.

```python
import bgpkit
import requests

# Make request manually to inspect response
response = requests.get(
    "https://api.bgpkit.com/v3/broker/latest",
    params={},
    verify=True
)
print(f"Status: {response.status_code}")
print(f"Headers: {response.headers}")
print(f"Body: {response.text[:500]}")  # First 500 chars
```

--------------------------------

### Filter by Exact Prefix

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Creates a filter for an exact prefix match using CIDR notation.

```python
from bgpkit import Filter, Parser

# Filter by exact prefix
filter_obj = Filter.prefix("1.1.1.0/24")
parser = Parser.from_filters(url="...", filters=[filter_obj])
```

--------------------------------

### Analyze ROA Coverage by TAL

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Groups ROA data by Trust Anchor Location (TAL) to analyze coverage distribution.

```python
import bgpkit

roas = bgpkit.Roas()

# Get current ROAs for an AS
roas_data = roas.query(asn=15169, current=True)

# Analyze by TAL (Trust Anchor Location)
by_tal = {}
for roa in roas_data:
    tal = roa.tal or "unknown"
    if tal not in by_tal:
        by_tal[tal] = []
    by_tal[tal].append(roa)

for tal, items in by_tal.items():
    print(f"{tal}: {len(items)} ROAs")
```

--------------------------------

### Optimize Parsing Performance

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Use the lightweight RouteParser instead of the full Parser for faster MRT file processing.

```python
# Slow: Full parser with all fields
parser1 = bgpkit.Parser(url="file.mrt")

# Fast: Lightweight route parser
parser2 = bgpkit.RouteParser(url="file.mrt")
```

--------------------------------

### Handle API Errors with Python

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Implement robust error handling for network and parsing exceptions when querying AS information.

```python
import bgpkit
from requests.exceptions import RequestException

def safe_query(asn: str):
    """Query with error handling."""
    try:
        asn_lookup = bgpkit.AsnLookup()
        result = asn_lookup.query(asn=asn)
        return result.data[0] if result.data else None
    except RequestException as e:
        print(f"Network error: {e}")
        return None
    except (KeyError, ValueError) as e:
        print(f"Response parse error: {e}")
        return None
    except Exception as e:
        print(f"Unexpected error: {e}")
        return None

# Usage
info = safe_query("15169")
if info:
    print(f"AS{info.asn}: {info.name}")
```

--------------------------------

### Query Peer Information with Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Queries for peer information for a specific Autonomous System Number (ASN) using the BGPKIT Broker. The `full_feed` parameter can be set to True to retrieve all available peer data.

```python
# Query peer information
peers = broker.peers(asn=13335, full_feed=True)
```

--------------------------------

### Parse Data with Filters

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Configures a Parser with specific peer IP and prefix filters to narrow down the parsed elements.

```python
import bgpkit

parser = bgpkit.Parser(
    url="file:///data/updates.20240101.0000.gz",
    filters={
        "peer_ips": "192.0.2.1, 2001:db8::1",
        "prefixes": "1.1.1.0/24, 8.8.8.0/24"
    }
)

all_elements = parser.parse_all()
print(f"Parsed {len(all_elements)} matching elements")
```

--------------------------------

### Search BGP Data Files with Broker

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Uses the BGPKIT Broker to search for MRT data files within a specified time range. This is useful for finding historical BGP data.

```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))
```

--------------------------------

### Parse routes with RouteParser

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Utilize RouteParser for memory-efficient route-only parsing and counting.

```python
import bgpkit

# Fast route-only parsing
route_parser = bgpkit.RouteParser(
    url="https://spaces.bgpkit.org/parser/update-example"
)

# Count routes
total = route_parser.count()
print(f"Total routes: {total}")

# Iterate with minimal fields
for route in route_parser:
    print(f"{route.prefix} -> {route.as_path}")
```

--------------------------------

### Paginate API Results in Python

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Iterate through multiple pages of results to retrieve complete datasets for large queries.

```python
import bgpkit

def fetch_all_asns(country: str):
    """Fetch all ASs for a country with pagination."""
    asn_lookup = bgpkit.AsnLookup()
    all_asns = []
    page = 1
    
    while True:
        result = asn_lookup.query(
            country=country,
            page=page,
            page_size=100
        )
        all_asns.extend(result.data)
        
        if len(result.data) < result.page_size:
            break  # Last page
        page += 1
    
    return all_asns

# Get all US ASs
us_asns = fetch_all_asns("US")
print(f"Total US ASs: {len(us_asns)}")
```

--------------------------------

### BGP Community Lookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/README.md

Retrieves BGP community information for a given ASN, with options for pagination. It also shows how to list available community data sources.

```python
entries = bgpkit.CommunityLookup().query(asn="13335", page_size=50)
for entry in entries:
    print(entry.value, entry.description)

sources = bgpkit.CommunityLookup().sources()
```

--------------------------------

### Access AS Number Property

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Retrieve the AS number from an IpInfo result object, checking for existence before access.

```python
result = ip_lookup.query(ip="1.1.1.1")
if result.as_number:
    print(f"AS Number: {result.as_number}")
```

--------------------------------

### Validating Query Parameters

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Ensure input types are correct before initiating broker queries to prevent runtime errors. This wrapper pattern enforces string-based timestamps.

```python
def query_broker_safe(ts_start: str, ts_end: str) -> list:
    """Wrapper with parameter validation."""
    if not isinstance(ts_start, str) or not isinstance(ts_end, str):
        raise TypeError("Timestamps must be strings")
    
    broker = bgpkit.Broker()
    return broker.query(ts_start=ts_start, ts_end=ts_end)
```

--------------------------------

### Find Communities by AS

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-community.md

Queries communities associated with a specific Autonomous System number.

```python
import bgpkit

community_lookup = bgpkit.CommunityLookup()

# Get communities defined by Google
google_communities = community_lookup.query(asn="15169", page_size=100)
print(f"Google defines {len(google_communities)} communities:")
for entry in google_communities:
    print(f"  {entry.value}: {entry.description}")
```

--------------------------------

### Parse All Elements into a List

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Retrieves all BGP route elements from the source file as a list, useful for smaller datasets or when random access is required.

```python
parser = bgpkit.Parser(url="https://spaces.bgpkit.org/parser/update-example")
all_elements = parser.parse_all()
print(f"Parsed {len(all_elements)} elements")
for elem in all_elements[:10]:
    print(f"  {elem.prefix}")
```

--------------------------------

### bgpkit.CommunityLookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/configuration.md

Constructor and query method for BGP community lookup operations.

```APIDOC
## bgpkit.CommunityLookup

### Constructor
`bgpkit.CommunityLookup(api_url="https://api.bgpkit.com/v3/communities")`

- **api_url** (str) - Optional - Base URL for the communities API.

### Method: query()
Queries the community database with optional filters.

#### Parameters
- **asn** (str) - Optional - Filter by AS number.
- **value** (str) - Optional - Filter by community value.
- **description** (str) - Optional - Keyword search in description.
- **as_name** (str) - Optional - Filter by organization/AS name.
- **country** (str) - Optional - Filter by 2-letter country code.
- **page** (int) - Optional - Page number (0-indexed).
- **page_size** (int) - Optional - Results per page (1-1000).
```

--------------------------------

### Query IP Information

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Perform lookups for IPv4 or IPv6 addresses, optionally requesting simplified results.

```python
import bgpkit

ip_lookup = bgpkit.IpLookup()

# Query IP information
result = ip_lookup.query(ip="1.1.1.1")
print(f"IP: {result.ip}")
print(f"Country: {result.country}")
print(f"AS Number: {result.as_number}")
print(f"AS Name: {result.as_name}")

# Simple lookup (fewer details)
simple_result = ip_lookup.query(ip="8.8.8.8", simple=True)

# Full results
full_result = ip_lookup.query(ip="2001:4860:4860::8888")
if full_result.asn:
    print(f"AS details: {full_result.asn}")
```

--------------------------------

### Query Peers with Broker API

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Search for peer information by ASN, full-feed status, or specific IP address.

```python
import bgpkit

broker = bgpkit.Broker()

# Find all peers for Cloudflare (AS13335)
peers = broker.peers(asn=13335)
print(f"Cloudflare appears at {len(peers)} collectors")

# Find full-feed peers
full_feed = broker.peers(full_feed=True)
print(f"Found {len(full_feed)} full-feed peers")

# Query a specific peer
peer_info = broker.peers(ip="192.0.2.1")
if peer_info:
    p = peer_info[0]
    print(f"Peer {p.ip} (AS{p.asn}) at {p.collector}")
```

--------------------------------

### Paginate ROA Results

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Iterate through large result sets using page and page_size parameters.

```python
# Iterate through paginated results
all_roas = []
page = 1
while True:
    results = roas.query(asn=3333, page=page, page_size=10)
    if not results:
        break
    all_roas.extend(results)
    print(f"Page {page}: {len(results)} ROAs")
    if len(results) < 10:  # Last page
        break
    page += 1

print(f"Total ROAs for AS3333: {len(all_roas)}")
```

--------------------------------

### Parser.parse_all()

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Parses all elements from the specified MRT file and returns them as a complete list.

```APIDOC
## parse_all()

### Description
Parses all elements from the file and returns them as a list of RouteElem objects.

### Returns
- **List[RouteElem]** - A list containing all parsed BGP route elements.
```

--------------------------------

### Access AS Name Property

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-ip.md

Retrieve the organization name associated with the AS from an IpInfo result object.

```python
result = ip_lookup.query(ip="1.1.1.1")
if result.as_name:
    print(f"AS Organization: {result.as_name}")
```

--------------------------------

### Roas.query

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Queries the ROAs database for historical and current Route Origination Authorizations based on provided filters.

```APIDOC
## Roas.query(asn: int = None, prefix: str = None, date: str = None, current: bool = None, page: int = 1, page_size: int = None)

### Description
Queries the ROAs database for historical and current Route Origination Authorizations.

### Parameters
- **asn** (int) - Optional - Autonomous system number to filter ROAs.
- **prefix** (str) - Optional - IP prefix to filter ROAs (CIDR notation).
- **date** (str) - Optional - Query date in YYYY-MM-DD format for historical data.
- **current** (bool) - Optional - If True, return only currently valid ROAs. If False, include withdrawn ROAs.
- **page** (int) - Optional - Page number (1-indexed). Defaults to 1.
- **page_size** (int) - Optional - Results per page.

### Returns
- **List[RoasItem]** - A list of ROAs matching the query criteria.
```

--------------------------------

### Explore Collectors with Broker API

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/quick-start.md

Retrieve a list of active collectors filtered by project.

```python
import bgpkit

broker = bgpkit.Broker()

# Find all active collectors from Route Views
collectors = broker.collectors(project="routeviews", active=True)

for collector in collectors:
    print(f"{collector.id}: {collector.name}")
    print(f"  Location: {collector.country}")
    if collector.latitude:
        print(f"  Coordinates: ({collector.latitude}, {collector.longitude})")
```

--------------------------------

### Parse BGP elements with filters

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Use the Parser class to process MRT files with specific peer IP filters.

```python
import bgpkit
import json

# Parse with filtering
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"}
)

# Process all elements
for elem in parser:
    data = elem.to_dict()
    print(f"Prefix: {data['prefix']}")
    print(f"AS Path: {data.get('as_path', [])}")
    print(f"Origin: {data.get('origin', 'unknown')}")
    print()
```

--------------------------------

### Catching API Request Exceptions

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/errors-and-exceptions.md

Use RequestException to catch network-related errors during broker queries. Implement fallback logic within the except block to maintain application stability.

```python
from requests.exceptions import RequestException
import bgpkit

broker = bgpkit.Broker()

try:
    items = broker.query(ts_start="2024-01-01T00:00:00Z")
except RequestException as e:
    print(f"API error: {e}")
    # Implement fallback logic
```

--------------------------------

### Filter by Prefix Range

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-parser.md

Creates a filter for IP prefixes within a specified CIDR range.

```python
from bgpkit import Filter, Parser

# Filter by prefix range
filter_obj = Filter.prefix_range("1.0.0.0/8")
parser = Parser.from_filters(url="...", filters=[filter_obj])
```

--------------------------------

### Perform Historical ROA Lookup

Source: https://github.com/bgpkit/pybgpkit/blob/main/_autodocs/api-reference-roas.md

Compare current ROA data against historical records for a specific date.

```python
# Compare current vs historical
current = roas.query(asn=3333, current=True)
print(f"RIPE NCC current ROAs: {len(current)}")

historical = roas.query(asn=3333, date="2018-01-01")
print(f"RIPE NCC ROAs on 2018-01-01: {len(historical)}")

# Show RPKI TALs
tal_counts = {}
for roa in current:
    tal = roa.tal or "unknown"
    tal_counts[tal] = tal_counts.get(tal, 0) + 1

for tal, count in tal_counts.items():
    print(f"  {tal}: {count} ROAs")
```