Skip to content

Latest commit

 

History

History
330 lines (241 loc) · 6.47 KB

File metadata and controls

330 lines (241 loc) · 6.47 KB

Python API Reference

Programmatic usage of the DNS Benchmarking Tool.


Quick Start

from src.blocklist import BlocklistManager
from src.dns import create_query_engine_from_config
from src.testing import BenchmarkRunner

# Run a benchmark
blocklist_manager = BlocklistManager()
blocklist_manager.load_blocklists_sync(categories=["ads"])

query_engine = create_query_engine_from_config()
runner = BenchmarkRunner(blocklist_manager, query_engine)

results = runner.run_benchmark_sync(
    categories=["ads"],
    domains_per_category=50
)

Blocklist Module

BlocklistManager

from src.blocklist import BlocklistManager

manager = BlocklistManager()

# Load blocklists
manager.load_blocklists_sync(categories=["ads", "malware"])

# Get domains for testing
domains = manager.get_test_domains(
    categories=["ads"],
    domains_per_category=100,
    include_legitimate=True
)

# Get statistics
stats = manager.get_statistics()
print(stats)

BlocklistFetcher

from src.blocklist import BlocklistFetcher

fetcher = BlocklistFetcher()

# Fetch blocklists (async)
import asyncio
results = asyncio.run(fetcher.fetch_blocklists(categories=["ads"]))

# Clear cache
fetcher.clear_cache()

# Get cache info
info = fetcher.get_cache_info()

DNS Module

DNSResolver

from src.dns import DNSResolver

async def query_example():
    async with DNSResolver() as resolver:
        # Query single service
        response = await resolver.query_by_name(
            domain="example.com",
            service_name="Quad9 Filtered"
        )
        print(f"Blocked: {response.blocked}")
        print(f"Latency: {response.latency_ms}ms")
        print(f"IPs: {response.ip_addresses}")
        
        # Query all filtered services
        results = await resolver.query_all_services(
            domain="ads.example.com",
            filtered_only=True
        )
        for name, resp in results.items():
            print(f"{name}: {'Blocked' if resp.blocked else 'Allowed'}")

import asyncio
asyncio.run(query_example())

QueryEngine

from src.dns import create_query_engine_from_config
from src.utils import get_config

config = get_config()
engine = create_query_engine_from_config()

async def batch_query():
    domains = [("example.com", "test"), ("ads.google.com", "ads")]
    services = config.filtered_services[:3]
    
    results = await engine.execute_batch(
        domains=domains,
        services=services,
        show_progress=True
    )
    
    for result in results:
        print(f"{result.domain} via {result.service_name}: {result.blocked}")

import asyncio
asyncio.run(batch_query())

Testing Module

BenchmarkRunner

from src.blocklist import BlocklistManager
from src.dns import create_query_engine_from_config
from src.testing import BenchmarkRunner

# Initialize
manager = BlocklistManager()
manager.load_blocklists_sync(categories=["ads", "malware"])

engine = create_query_engine_from_config()
runner = BenchmarkRunner(manager, engine)

# Run benchmark
run = runner.run_benchmark_sync(
    categories=["ads", "malware"],
    services=["AdGuard DNS", "Quad9 Filtered"],
    domains_per_category=100,
    include_baseline=True,
    include_legitimate=True
)

# Access results
print(f"Run ID: {run.run_id}")
print(f"Total queries: {len(run.results)}")

for service, metrics in run.service_metrics.items():
    print(f"{service}: {metrics.overall_blocking.block_rate:.1%} block rate")

MetricsCalculator

from src.testing import MetricsCalculator

calculator = MetricsCalculator()

# Calculate from results
service_metrics = calculator.calculate_service_metrics(
    results=query_results,
    expected_blocked={"ads.example.com": True, "google.com": False}
)

for service, metrics in service_metrics.items():
    print(f"{service}:")
    print(f"  Block Rate: {metrics.overall_blocking.block_rate:.1%}")
    print(f"  Accuracy: {metrics.overall_blocking.accuracy:.1%}")
    print(f"  Avg Latency: {metrics.latency.avg_ms:.1f}ms")

Reporting Module

ReportGenerator

from src.reporting import ReportGenerator
from src.testing import BenchmarkRunner

# After running benchmark
generator = ReportGenerator()

# Generate reports
paths = generator.generate_from_run(
    run=benchmark_run,
    formats=["html", "json"],
    include_charts=True
)

print(f"Generated: {paths}")

Visualizer

from src.reporting import Visualizer
from pathlib import Path

visualizer = Visualizer(output_dir=Path("reports/charts"))

# Create all charts
charts = visualizer.create_all_charts(
    run=benchmark_run,
    save_html=True,
    save_png=False
)

Utils Module

Config

from src.utils import get_config

config = get_config()

# Access services
for service in config.filtered_services:
    print(f"{service.name}: {service.endpoint} ({service.protocol})")

# Access settings
print(f"Timeout: {config.test_settings.query_timeout}s")
print(f"Max concurrent: {config.test_settings.max_concurrent}")

Database

from src.utils import get_database

db = get_database()

# Get test runs
runs = db.get_all_test_runs(limit=10)
for run in runs:
    print(f"Run {run['id']}: {run['status']}")

# Get results for a run
results = db.get_query_results(run_id=5)

Data Classes

DNSResponse

@dataclass
class DNSResponse:
    domain: str
    query_type: str
    response_code: str
    response_code_int: int
    ip_addresses: List[str]
    cname_records: List[str]
    latency_ms: float
    ttl: Optional[int]
    blocked: bool
    error: Optional[str]
    
    @property
    def success(self) -> bool: ...
    
    @property
    def is_nxdomain(self) -> bool: ...

QueryResult

@dataclass
class QueryResult:
    task: QueryTask
    response: DNSResponse
    timestamp: datetime
    error_type: ErrorType
    
    @property
    def domain(self) -> str: ...
    
    @property
    def blocked(self) -> bool: ...
    
    @property
    def latency_ms(self) -> float: ...

ServiceMetrics

@dataclass
class ServiceMetrics:
    service_name: str
    latency: LatencyMetrics
    overall_blocking: BlockRateMetrics
    category_blocking: Dict[str, BlockRateMetrics]
    cache: CacheMetrics

Async Context Managers

# DNSResolver
async with DNSResolver() as resolver:
    response = await resolver.query(...)

# QueryEngine
async with create_query_engine_from_config() as engine:
    results = await engine.execute_batch(...)