cnb_exchange_rates/README.md

CNB Exchange Rates

Tento projekt je určen pro stahování a správu kurzů cizích měn vůči české koruně (CZK) z webu České národní banky (ČNB). Data jsou ukládána do interní SQLite databáze a lze je vyhledávat podle data a kódu měny.

Funkce

• Stahování dat:
  • Roční data pro celý rok.
  • Měsíční data pro konkrétní měnu a časové období.
  • Denní data pro konkrétní datum.
• Interní databáze: Všechna stažená data jsou ukládána do SQLite databáze pro rychlé vyhledávání.
• Vyhledávání kurzů: Lze vyhledat kurz pro zadané datum a měnu. Pokud kurz pro dané datum neexistuje, program aplikuje pravidla pro víkendy a státní svátky.
• Správa státních svátků: Program obsahuje seznam státních svátků v ČR a umí je rozpoznat.
• Kontrola data a času: Program kontroluje, zda jsou požadovaná data již k dispozici. Pro dnešní datum před 14:30 a pro budoucí data vrací chybu.
• Automatické stahování: Lze aktivovat automatické stahování denních dat pro dnešní datum po 14:30.
• Kontrola konzistence ročních dat: Při startu programu automaticky kontroluje, zda roční data pro aktuální rok obsahují záznamy za poslední 3 pracovní dny. Pokud ne, data jsou automaticky aktualizována.
• Automatické stahování ročních dat: Pokud jsou požadována data pro rok, který v databázi není, program automaticky stáhne roční data pro daný rok, aktualizuje databázi a teprve poté vrátí výsledek.
• Generování reportů: Lze vygenerovat report kurzů pro zadaný rok, měsíc nebo časové období včetně dopočítaných kurzů pro dny, kdy ve vstupních datech neexistovali.
• Správné dopočítání kurzů: Program správně aplikuje pravidla ČNB pro dopočítání kurzů pro víkendy a svátky jak při vyhledávání (--get-rate), tak při generování reportů.
• Výpočet Jednotného kurzu: Lze vypočítat 'Jednotný kurz' pro daňové účely podle metodiky ČNB jako aritmetický průměr kurzů k posledním dnům každého měsíce v roce.
• Validace dat: Program umí validovat data pro konzistenci, detekovat změny kurzů přesahující prahové hodnoty, kontrolovat počet obchodních dnů a analyzovat časové mezery v datech.
• Analýza počtu záznamů: Lze zobrazit počty záznamů podle různých časových období (týden, měsíc, čtvrtletí, pololetí, rok).
• Adaptivní prahy: Systém se učí z historických dat a automaticky upravuje prahy pro detekci anomálií.
• JSON výstup: Všechny příkazy podporují JSON formát pro programové zpracování pomocí přepínače --json.

Požadavky

• Python 3.6 nebo vyšší
• Knihovny: requests

Instalace

1. Naklonujte repozitář:

   git clone <url-repozitare>
   cd cnb_exchange_rates
   

2. Nainstalujte požadované knihovny:

   pip install requests
   

Použití

Spuštění CLI

Všechny operace se provádějí pomocí skriptu src/cli.py.

python src/cli.py [argumenty]

Při každém spuštění programu:

1. Automaticky inicializuje databázi.
2. Zkontroluje konzistenci ročních dat pro aktuální rok. Pokud data neobsahují záznamy za poslední 3 pracovní dny, jsou automaticky aktualizována.

Argumenty

• --year ROK: Stáhne roční data pro zadaný rok.
• -c, --currency MENA: Kód měny (např. USD) pro měsíční stahování, vyhledání kurzu nebo generování reportu.
• --start-date ZACATEK: Počáteční datum pro měsíční stahování nebo generování reportu. Formát: DD.MM.YYYY.
• --end-date KONEC: Koncové datum pro měsíční stahování nebo generování reportu. Formát: DD.MM.YYYY.
• --date DATUM: Stáhne denní data pro zadané datum. Formát: DD.MM.YYYY.
• --get-rate DATUM: Vyhledá kurz pro zadané datum. Formát: DD.MM.YYYY. Vyžaduje -c nebo --currency.
• --auto-download: Povolí automatické stahování denních dat pro dnešní datum, pokud je po 14:30 a kurz není k dispozici.
• --report-year ROK [--report-month MESIC]: Vygeneruje report kurzů pro zadaný rok (a případně měsíc). Vyžaduje -c nebo --currency.
• --report-period ZACATEK KONEC: Vygeneruje report kurzů pro zadané časové období. Vyžaduje -c nebo --currency.
• --stats [ROK]: Vypočítá 'Jednotný kurz' pro daňové účely podle metodiky ČNB. Pokud je zadán rok, vytvoří kurz pro konkrétní rok. Pokud není rok zadán, vytvoří kurzy pro všechny roky s dostupnými daty. Vyžaduje -c nebo --currency.
• --validate: Validuje data pro měnu nebo všechny měny. Zkontroluje konzistenci kurzů, počet obchodních dnů a detekuje možné chyby.
• --record-counts: Zobrazí počet záznamů podle časových období (týden, měsíc, čtvrtletí, pololetí, rok). Vyžaduje -c nebo --currency.
• --change-threshold PRAH: Práh pro detekci změn kurzů v procentech (výchozí: 1.0).
• --no-adaptive: Vypne adaptivní učení prahů na základě historických dat.
• --gap-threshold DNY: Maximální přijatelná mezera v pracovních dnech (výchozí: 3).
• --json: Výstup ve formátu JSON místo prostého textu pro programové zpracování.

Příklady

1. Stažení ročních dat pro rok 2020:

   python src/cli.py --year 2020
   

2. Stažení měsíčních dat pro měnu USD v lednu 2025:

   python src/cli.py -c USD --start-date 01.01.2025 --end-date 31.01.2025
   

3. Stažení denních dat pro datum 08.08.2025:

   python src/cli.py --date 08.08.2025
   

4. Vyhledání kurzu USD pro datum 08.08.2025:

   python src/cli.py --get-rate 08.08.2025 -c USD
   

5. Vyhledání kurzu USD pro víkendové datum 10.08.2025 (použije kurz z předchozího pracovního dne):

   python src/cli.py --get-rate 10.08.2025 -c USD
   

6. Vyhledání kurzu USD pro dnešní datum po 14:30 s automatickým stažením dat (pokud nejsou k dispozici):

   python src/cli.py --get-rate DD.MM.YYYY -c USD --auto-download
   

   (Nahraďte DD.MM.YYYY aktuálním datem)

7. Vygenerování ročního reportu kurzů pro USD za rok 2020:

   python src/cli.py --report-year 2020 -c USD
   

8. Vygenerování měsíčního reportu kurzů pro USD za červenec 2020:

   python src/cli.py --report-year 2020 --report-month 7 -c USD
   

9. Vygenerování reportu kurzů pro USD za období 01.07.2020 - 31.07.2020:

   python src/cli.py --report-period 01.07.2020 31.07.2020 -c USD
   

10. Výpočet Jednotného kurzu pro daňové účely pro USD za rok 2025:

    python src/cli.py --stats 2025 -c USD
    

11. Výpočet Jednotného kurzu pro daňové účely pro všechny roky s daty:

    python src/cli.py --stats -c USD
    

12. Validace dat pro měnu USD za rok 2025:

    python src/cli.py --validate --currency USD --year 2025
    

13. Validace všech měn s vlastními prahy:

    python src/cli.py --validate --change-threshold 0.5 --gap-threshold 2
    

14. Zobrazení počtu záznamů podle časových období pro USD:

    python src/cli.py --record-counts --currency USD --year 2025
    

15. Získání posledního dostupného kurzu USD:

    python src/cli.py -c USD
    

16. JSON výstup pro vyhledání kurzu:

    python src/cli.py --get-rate 01.01.2025 -c USD --json
    

17. JSON výstup pro validaci dat:

    python src/cli.py --validate --currency USD --year 2025 --json
    

JSON formát

Při použití přepínače --json program vrací strukturovaná data ve formátu JSON:

Jednotlivý kurz

{
  "currency": "USD",
  "rate": 24.214,
  "date": "01.01.2025",
  "timestamp": "2025-01-12T10:30:00Z"
}

Jednotný kurz pro jeden rok

{
  "currency": "USD",
  "year": 2025,
  "unified_rate": 21.84,
  "calculation_date": "2025-01-12T10:30:00Z"
}

Jednotný kurz pro více let

{
  "currency": "USD",
  "results": [
    {"year": 2023, "unified_rate": 23.45},
    {"year": 2024, "unified_rate": 23.28},
    {"year": 2025, "unified_rate": 21.84}
  ],
  "calculation_date": "2025-01-12T10:30:00Z"
}

Poslední dostupný kurz

{
  "currency": "USD",
  "rate": 20.632,
  "date": "31.12.2025",
  "timestamp": "2025-01-12T10:30:00Z"
}

Chyba

{
  "error": "Kurz nebyl nalezen",
  "code": "RATE_NOT_FOUND",
  "timestamp": "2025-01-12T10:30:00Z"
}

Validace dat

{
  "currency": "USD",
  "validation_year": 2025,
  "adaptive_analysis": {
    "adaptive_threshold": 1.5,
    "base_threshold": 1.0,
    "volatility_percent": 0.24,
    "data_points": 62
  },
  "price_change_violations": [
    {
      "date": "06.01.2025",
      "change_percent": 1.19,
      "severity": "minor"
    }
  ],
  "temporal_gaps": [],
  "trading_days_validation": {
    "expected_trading_days": 251,
    "actual_data_points": 251,
    "discrepancy_days": 0,
    "data_completeness_percent": 100.0
  },
  "record_counts_by_period": {
    "2025": {
      "year": 251,
      "half_year": {"H1": 124, "H2": 127},
      "quarter": {"Q1": 63, "Q2": 61, "Q3": 66, "Q4": 61},
      "month": {"01": 22, "02": 20, "03": 21},
      "week": {"W01": 5, "W02": 5}
    }
  },
  "data_quality_score": 95
}

Počty záznamů podle období

{
  "currency": "USD",
  "record_counts": {
    "2025": {
      "year": 251,
      "half_year": {"H1": 124, "H2": 127},
      "quarter": {"Q1": 63, "Q2": 61, "Q3": 66, "Q4": 61},
      "month": {"01": 22, "02": 20, "03": 21, "04": 20},
      "week": {"W01": 5, "W02": 5, "W03": 5}
    }
  }
}

Chování při různých časech a datumech

• Budoucí datum: Program vrátí chybu, protože kurzy pro budoucí data ještě nebyly vydány.
• Dnešní datum před 14:30: Program vrátí chybu, protože kurzy jsou vyhlašovány po 14:30.
• Dnešní datum po 14:30: Program vyhledá kurz. Pokud není k dispozici a je aktivní --auto-download, automaticky stáhne denní data.
• Minulé datum: Program vyhledá kurz. Pokud není k dispozici, aplikuje pravidla pro víkendy a státní svátky.

Automatická kontrola konzistence ročních dat

Při každém spuštění programu:

1. Zkontroluje, zda roční data pro aktuální rok obsahují záznamy za poslední 3 pracovní dny.
2. Pokud záznamy chybí, automaticky stáhne aktualizovaná roční data.
3. Tímto způsobem je zajištěna konzistence dat pro aktuální rok, protože každý den přibývají nové záznamy.

Automatické stahování ročních dat při vyhledávání

Pokud při vyhledávání kurzu zjistí program, že databáze neobsahuje data pro požadovaný rok:

1. Automaticky stáhne roční data pro daný rok.
2. Aktualizuje databázi.
3. Teprve poté vyhledá a vrátí kurz.

Generování reportů o kurzech

Program umí vygenerovat reporty kurzů pro zadaný rok, měsíc nebo časové období. Reporty obsahují:

• Kurzy pro všechny dny v zadaném období.
• Dopočítané kurzy pro dny, kdy ve vstupních datech neexistovali (např. víkendy, svátky).
• Poznámky o tom, zda byl kurz nalezen v databázi nebo dopočítán.

Výstupní soubory jsou ve formátu CSV a jsou uloženy v adresáři data/.

Správné dopočítání kurzů pro víkendy a svátky

Program správně aplikuje pravidla ČNB pro dopočítání kurzů:

• Pro víkendy a svátky: Použije se kurz z posledního dne před nimi, který měl kurz vyhlášený pro tento víkend/svátek.
• Pro běžné dny bez kurzu: Použije se kurz z posledního pracovního dne před ním.

Příklad:

• 1.1.2021 (pátek) - svátek, kurz 21.387
• 2.1.2021 (sobota) - víkend, žádný kurz → použije se kurz 21.387 z 1.1.2021
• 3.1.2021 (neděle) - víkend, žádný kurz → použije se kurz 21.387 z 1.1.2021

Tato logika je aplikována jak při vyhledávání kurzu pomocí --get-rate, tak při generování reportů.

Struktura projektu

• src/: Zdrojové kódy.
  • cli.py: Hlavní skript s CLI rozhraním.
  • data_fetcher.py: Funkce pro stahování dat z ČNB.
  • database.py: Funkce pro práci s SQLite databází.
  • holidays.py: Funkce pro práci se státními svátky.
  • rate_finder.py: Funkce pro vyhledávání kurzů.
  • rate_reporter.py: Funkce pro generování reportů o kurzech.
• data/: Adresář pro ukládání stažených dat a databáze.
  • exchange_rates.db: SQLite databáze s kurzy.
  • holidays.json: Seznam státních svátků v ČR.
  • *.csv: Stažená data a reporty v CSV formátu.
• tests/: Testy jednotlivých modulů.

Testování

Pro spuštění testů přejděte do adresáře projektu a spusťte:

python tests/test_holidays.py
python tests/test_data_fetcher.py
python tests/test_rate_finder.py
python tests/test_data_consistency.py
python tests/test_auto_yearly_download.py
python tests/test_rate_reporter.py
python tests/test_rate_calculation.py

Licence

Tento projekt je licencován pod MIT licencí.