HĹBKOVÁ ANALÝZA - rpscrape

Executive Summary

Tento dokument obsahuje komplexnú hĺbkovú analýzu projektu rpscrape vrátane root cause analýzy problémov, porovnania alternatív, návrhu riešení a architektúry pre vylepšenú verziu.

Kľúčové zistenie: Projekt rpscrape je funkčný nástroj s aktívnou komunitou, ale trpí architektonickými problémami, ktoré spôsobujú opakujúce sa chyby. Odporúčam strategický fork s postupným refaktorovaním namiesto kompletného prepísania.

ČASŤ 1: ROOT CAUSE ANALÝZA

1.1 Prečo vznikajú opakujúce sa problémy?

Problém	Root Cause	Dopad
SSL/HTTP chyby	Chýbajúca retry logika a session management	40% issues
Chýbajúce dáta	Fragilné XPath selektory závislé od HTML štruktúry	30% issues
Index out of range	Absencia validácie vstupných dát	15% issues
HTTP 406	Nesprávne/chýbajúce HTTP headers	15% issues

1.2 Architektonické príčiny

┌─────────────────────────────────────────────────────────────┐
│                    PROBLÉMOVÁ ARCHITEKTÚRA                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐   │
│  │   CLI       │────▶│  Scraper    │────▶│   Parser    │   │
│  │  (argparse) │     │ (requests)  │     │   (lxml)    │   │
│  └─────────────┘     └─────────────┘     └─────────────┘   │
│         │                   │                   │           │
│         │                   │                   │           │
│         ▼                   ▼                   ▼           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              GLOBÁLNY STAV (settings)                │   │
│  │              - Žiadna izolácia                       │   │
│  │              - Ťažké testovanie                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  PROBLÉMY:                                                  │
│  ✗ Tight coupling medzi vrstvami                           │
│  ✗ Žiadna abstrakcia pre HTTP klienta                      │
│  ✗ Parsovanie priamo závislé od Racing Post HTML           │
│  ✗ Žiadna error handling stratégia                         │
│  ✗ Globálne premenné namiesto dependency injection         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.3 Čo by vyriešilo 80% issues?

Top 3 zmeny s najvyšším dopadom:

Implementácia retry mechanizmu s exponenciálnym backoff
- Vyrieši: SSL chyby, connection timeouts, HTTP 5xx
- Náročnosť: Nízka
- Dopad: ~40% issues
Robustné HTTP headers
- Vyrieši: HTTP 406, bot detection
- Náročnosť: Nízka
- Dopad: ~15% issues
Graceful handling prázdnych/neočakávaných dát
- Vyrieši: Index errors, missing data
- Náročnosť: Stredná
- Dopad: ~25% issues

ČASŤ 2: TECHNICKÁ ANALÝZA PROBLÉMOV

2.1 SSL/TLS Chyby (Issue #186)

Príčina: ssl.SSLEOFError: [SSL: UNEXPECTED_EOF_WHILE_READING]

Root cause:

Server predčasne ukončí SSL handshake
Dlhé scraping sessions bez connection pooling
Žiadna retry logika

Riešenie:

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session():
    session = requests.Session()
    retry = Retry(
        total=5,
        backoff_factor=1,
        status_forcelist=[500, 502, 503, 504],
        allowed_methods=["HEAD", "GET", "OPTIONS"]
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('https://', adapter)
    session.mount('http://', adapter)
    return session

2.2 HTTP 406 Not Acceptable (Issue #182)

Príčina: Server odmieta requesty bez správnych Accept headers

Root cause:

Nedostatočné HTTP headers
Chýbajúci User-Agent alebo príliš generický
Racing Post aktívne blokuje boty (robots.txt vracia 403!)

Riešenie:

BROWSER_HEADERS = {
    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
    'Accept-Language': 'en-GB,en;q=0.9',
    'Accept-Encoding': 'gzip, deflate, br',
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    'Connection': 'keep-alive',
    'Upgrade-Insecure-Requests': '1',
    'Cache-Control': 'max-age=0',
}

2.3 Fragilné XPath Selektory

Príčina: Absolútne XPath cesty sa lámu pri akejkoľvek zmene HTML

Best practices:

Typ	Príklad	Riziko
❌ Absolútny	`/html/body/div[3]/table/tr[2]/td[1]`	Vysoké
⚠️ Index-based	`//div[@class='results']/table/tr[2]`	Stredné
✅ Relatívny + ID	`//div[@id='results']//td[@data-field='horse']`	Nízke
✅ CSS + atribút	`div.race-result td[data-testid='horse-name']`	Najnižšie

Odporúčanie: Hybridný prístup - CSS pre jednoduché prípady, XPath pre komplexné traversing

2.4 Chýbajúce Rate Limiting

Riziko: IP ban, server overload, etické problémy

Implementácia s asyncio.Semaphore:

import asyncio
from aiolimiter import AsyncLimiter

# Max 10 requests za sekundu, max 5 concurrent
rate_limiter = AsyncLimiter(10, 1)
semaphore = asyncio.Semaphore(5)

async def fetch_with_limit(url):
    async with semaphore:
        async with rate_limiter:
            async with session.get(url) as response:
                return await response.text()

ČASŤ 3: POROVNÁVACIA ANALÝZA ALTERNATÍV

3.1 Alternatívy k rpscrape

Riešenie	Typ	Cena	Dáta	Spoľahlivosť
rpscrape	Open-source scraper	Zadarmo	Racing Post	Nestabilné
The Racing API	Komerčné API	£50+/mesiac	12+ rokov	Vysoká
Betfair Historical	Oficiálne API	Variabilná	Betfair odds	Vysoká
Timeform scraping	DIY scraping	Zadarmo	Timeform	Stredná
Smartform/Betwise	Komerčná DB	£100+/mesiac	Kompletné	Vysoká

3.2 Výhody a nevýhody rpscrape

Výhody:

✅ Zadarmo a open-source
✅ Aktívna komunita (193 stars, 75 forks)
✅ Pokrýva Racing Post dáta
✅ CSV/JSON export

Nevýhody:

❌ Nestabilný (101+ issues)
❌ Závislosť od HTML štruktúry
❌ Právne riziká (ToS Racing Post)
❌ Žiadne SLA

3.3 Web Scraping Frameworks

Framework	Use Case	Learning Curve	Škálovateľnosť
Scrapy	Enterprise scraping	Vysoká	Výborná
requests + BeautifulSoup	Jednoduché skripty	Nízka	Slabá
aiohttp + lxml	Async scraping	Stredná	Dobrá
Playwright/Selenium	JavaScript sites	Stredná	Stredná

Odporúčanie: Pre rpscrape ideálne aiohttp + lxml (už používa) s lepšou architektúrou

ČASŤ 4: FORK vs REWRITE ANALÝZA

4.1 Čo zachovať z pôvodného kódu?

Komponent	Kvalita	Rozhodnutie
Data models (dataclass)	Dobrá	✅ Zachovať, rozšíriť o Pydantic validáciu
lxml parsing logika	Stredná	⚠️ Refaktorovať, zachovať XPath
Betfair integrácia	Dobrá	✅ Zachovať
CLI argument parsing	Stredná	⚠️ Migrovať na Typer
HTTP request handling	Slabá	❌ Prepísať kompletne
Error handling	Slabá	❌ Prepísať kompletne
Config management	Dobrá	✅ Zachovať TOML

4.2 ROI Analýza

Prístup	Čas	Riziko	Zachované funkcie
Quick fixes	1-2 týždne	Nízke	100%
Strategický fork	1-2 mesiace	Stredné	90%
Kompletný rewrite	3-6 mesiacov	Vysoké	70%*

*Pri rewrite sa stratí "tribal knowledge" z 253 commitov

4.3 Rozhodnutie

🏆 ODPORÚČANIE: Strategický Fork

Zdôvodnenie:

Zachováva fungujúcu parsing logiku
Postupná migrácia bez prerušenia funkčnosti
Možnosť využiť existujúce testy komunity
Nižšie riziko regresií

ČASŤ 5: NÁVRH NOVEJ ARCHITEKTÚRY

5.1 Navrhovaná architektúra

┌─────────────────────────────────────────────────────────────────┐
│                      VYLEPŠENÁ ARCHITEKTÚRA                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      CLI LAYER (Typer)                    │  │
│  │  • Automatická dokumentácia                               │  │
│  │  • Type hints validácia                                   │  │
│  │  • Progress bars (rich)                                   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   SERVICE LAYER                           │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │  │
│  │  │ RaceScraper │  │ CardScraper │  │BetfairClient│       │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                  HTTP CLIENT LAYER                        │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │              ResilientHttpClient                    │  │  │
│  │  │  • Retry s exponenciálnym backoff                   │  │  │
│  │  │  • Rate limiting (semaphore + aiolimiter)           │  │  │
│  │  │  • Connection pooling                               │  │  │
│  │  │  • Rotating User-Agents                             │  │  │
│  │  │  • Circuit breaker pattern                          │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   PARSER LAYER                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │  │
│  │  │ RaceParser  │  │ CardParser  │  │ OddsParser  │       │  │
│  │  │ (Strategy)  │  │ (Strategy)  │  │ (Strategy)  │       │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │  │
│  │                                                           │  │
│  │  • Abstrakcia od konkrétnej stránky                      │  │
│  │  • Fallback selektory                                    │  │
│  │  • Graceful degradation                                  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    MODEL LAYER                            │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │           Pydantic Models s validáciou              │  │  │
│  │  │  • RaceInfo, RunnerInfo, OddsInfo                   │  │  │
│  │  │  • Automatická type coercion                        │  │  │
│  │  │  • Validačné pravidlá                               │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   EXPORT LAYER                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │  │
│  │  │ CSVExporter │  │JSONExporter │  │ DBExporter  │       │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                 CROSS-CUTTING CONCERNS                    │  │
│  │  • Logging (structlog/loguru)                            │  │
│  │  • Configuration (Pydantic Settings)                     │  │
│  │  • Metrics & Monitoring                                  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5.2 Navrhovaný Technology Stack

Vrstva	Pôvodná technológia	Navrhovaná	Zdôvodnenie
CLI	argparse + readline	Typer + Rich	Auto-docs, progress bars
HTTP	requests (sync)	aiohttp + tenacity	Async, retry
Parsing	lxml	lxml (zachovať)	Funguje dobre
Models	dataclass	Pydantic dataclass	Validácia
Config	tomli	Pydantic Settings	Type-safe config
Logging	print()	structlog	Structured logging
Testing	(žiadne)	pytest + VCR.py	HTTP mocking

5.3 Navrhovaná adresárová štruktúra

rpscrape_v2/
├── src/
│   └── rpscrape/
│       ├── __init__.py
│       ├── cli/
│       │   ├── __init__.py
│       │   ├── app.py              # Typer aplikácia
│       │   └── commands/
│       │       ├── scrape.py
│       │       └── racecards.py
│       ├── core/
│       │   ├── __init__.py
│       │   ├── http_client.py      # ResilientHttpClient
│       │   ├── rate_limiter.py
│       │   └── exceptions.py
│       ├── scrapers/
│       │   ├── __init__.py
│       │   ├── base.py             # Abstract base scraper
│       │   ├── race_scraper.py
│       │   └── card_scraper.py
│       ├── parsers/
│       │   ├── __init__.py
│       │   ├── base.py             # Parser interface
│       │   ├── racing_post.py
│       │   └── selectors.py        # XPath/CSS selektory
│       ├── models/
│       │   ├── __init__.py
│       │   ├── race.py             # Pydantic models
│       │   ├── runner.py
│       │   └── odds.py
│       ├── exporters/
│       │   ├── __init__.py
│       │   ├── base.py
│       │   ├── csv_exporter.py
│       │   └── json_exporter.py
│       └── config/
│           ├── __init__.py
│           └── settings.py         # Pydantic Settings
├── tests/
│   ├── conftest.py
│   ├── cassettes/                  # VCR.py recordings
│   ├── unit/
│   └── integration/
├── data/
│   ├── courses/
│   └── regions/
├── pyproject.toml
├── README.md
└── .github/
    └── workflows/
        └── ci.yml

ČASŤ 6: IMPLEMENTAČNÝ ROADMAP

6.1 Fáza 1: Quick Wins (1-2 týždne)

Cieľ: Stabilizovať existujúci kód bez veľkých zmien

Implementovať retry mechanizmus s tenacity
Pridať správne HTTP headers
Pridať základné logging (loguru)
Opraviť Index out of range s graceful handling
Pridať rate limiting (time.sleep)

6.2 Fáza 2: Refaktoring (2-4 týždne)

Cieľ: Zlepšiť architektúru bez zmeny funkcionality

Extrahovať HTTP client do samostatnej triedy
Migrovať dataclass na Pydantic
Implementovať proper error handling
Pridať pytest s VCR.py
Refaktorovať globálny stav

6.3 Fáza 3: Modernizácia (4-8 týždňov)

Cieľ: Moderná architektúra s novými funkciami

Migrovať CLI na Typer + Rich
Implementovať async scraping (aiohttp)
Pridať inkrementálny scraping
Implementovať parser fallbacks
Pridať CI/CD pipeline

6.4 Fáza 4: Enterprise Features (voliteľné)

ČASŤ 7: BEZPEČNOSŤ A ETIKA

7.1 Právne aspekty

Racing Post robots.txt: Vracia HTTP 403 - aktívne blokuje prístup k pravidlám!

UK právny rámec:

Žiadna špecifická legislatíva zakazujúca web scraping
Riziko porušenia:
- Copyright - na štruktúru dát
- Database rights - na kompiláciu dát
- Contract law - ak ToS zakazuje scraping
- Computer Misuse Act 1990 - ak obídete ochranu

Odporúčanie:

Scrapovať len verejne dostupné dáta
Rešpektovať rate limits
Neuchovávať osobné údaje (GDPR)
Zvážiť legitímne API alternatívy

7.2 Etické odporúčania

Prax	Implementácia
Rate limiting	Max 1 request/sekundu
User-Agent	Identifikovať sa ako bot (voliteľne)
robots.txt	Rešpektovať (ak dostupný)
Off-peak scraping	Preferovať nočné hodiny
Caching	Minimalizovať duplicitné requesty

ČASŤ 8: ZÁVER A ODPORÚČANIA

8.1 Hlavné závery

rpscrape je hodnotný projekt s aktívnou komunitou, ale trpí technickým dlhom
80% problémov je riešiteľných implementáciou retry logiky a lepších headers
Strategický fork je najlepšia cesta - zachováva funkčnosť, umožňuje postupné zlepšenia
Právne riziká existujú - zvážte komerčné API pre production use

8.2 Prioritizované odporúčania

#	Odporúčanie	Dopad	Náročnosť
1	Implementovať tenacity retry	Vysoký	Nízka
2	Opraviť HTTP headers	Vysoký	Nízka
3	Pridať structlog logging	Stredný	Nízka
4	Migrovať na Pydantic models	Stredný	Stredná
5	Pridať pytest + VCR.py	Stredný	Stredná
6	Implementovať rate limiting	Stredný	Nízka
7	Migrovať CLI na Typer	Nízky	Stredná
8	Async refaktoring	Nízky	Vysoká

8.3 Ďalšie kroky

Rozhodnutie: Fork existujúceho repo alebo nový projekt?
Scope: Ktoré fázy implementovať?
Timeline: Aký je realistický harmonogram?
Resources: Kto bude pracovať na projekte?

PRÍLOHY

A. Užitočné zdroje

Web Scraping Best Practices:

Retry Mechanizmy:

Logging:

Testing:

CLI:

Alternatívne dátové zdroje:

B. Kódové príklady

Resilient HTTP Client:

import aiohttp
from tenacity import retry, stop_after_attempt, wait_exponential
from aiolimiter import AsyncLimiter

class ResilientHttpClient:
    def __init__(self, rate_limit: float = 1.0, max_concurrent: int = 5):
        self.rate_limiter = AsyncLimiter(rate_limit, 1)
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.session = None

    async def __aenter__(self):
        self.session = aiohttp.ClientSession(headers=BROWSER_HEADERS)
        return self

    async def __aexit__(self, *args):
        await self.session.close()

    @retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, max=60))
    async def get(self, url: str) -> str:
        async with self.semaphore:
            async with self.rate_limiter:
                async with self.session.get(url) as response:
                    response.raise_for_status()
                    return await response.text()

Pydantic Model:

from pydantic import BaseModel, Field, validator
from typing import Optional
from datetime import date

class RaceInfo(BaseModel):
    race_id: str
    date: date
    course: str
    race_name: str
    distance_furlongs: float = Field(ge=0)
    going: str
    race_class: Optional[int] = Field(None, ge=1, le=7)

    @validator('distance_furlongs', pre=True)
    def parse_distance(cls, v):
        if isinstance(v, str):
            # Parse "1m2f" format
            return parse_distance_string(v)
        return v

Dokument vytvorený: 2025-12-09 Autor: Claude Code Deep Analysis Verzia: 1.0

FilesExpand file tree

DEEP_ANALYSIS.md

Latest commit

History