feat: Add JSON output support and auto-download functionality
- Add --json CLI flag for structured JSON output across all commands - Implement JSON formatting functions for different data types: * Single rate lookups with fallback information * Unified tax rates (single year and multi-year) * Last available rates * Error responses with codes and details - Add auto-download functionality for missing monthly data in tax calculations - Modify calculate_tax_yearly_average to automatically fetch missing months - Add rate limiting (1s delay) between API calls to be respectful - Update CLI argument parsing and output logic for JSON/text modes - Maintain full backward compatibility - existing commands work unchanged - Enhance documentation with JSON usage examples and schema - Update help text to include new --json option Features: - JSON output for programmatic consumption - Automatic data fetching for incomplete years - Structured error handling - Comprehensive documentation updates Breaking changes: None (fully backward compatible)
This commit is contained in:
kdusek
91
README.md
91
README.md
@@ -16,7 +16,9 @@ Tento projekt je určen pro stahování a správu kurzů cizích měn vůči če
|
||||
- **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ů.
|
||||
- **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.
|
||||
- **JSON výstup**: Všechny příkazy podporují JSON formát pro programové zpracování pomocí přepínače `--json`.
|
||||
|
||||
## Požadavky
|
||||
|
||||
@@ -60,8 +62,10 @@ Při každém spuštění programu:
|
||||
- `--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`.
|
||||
- `--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`.
|
||||
- `--json`: Výstup ve formátu JSON místo prostého textu pro programové zpracování.
|
||||
|
||||
### Příklady
|
||||
|
||||
@@ -111,6 +115,87 @@ Při každém spuštění programu:
|
||||
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**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
python src/cli.py --stats -c USD
|
||||
```
|
||||
|
||||
12. **Získání posledního dostupného kurzu USD**:
|
||||
```bash
|
||||
python src/cli.py -c USD
|
||||
```
|
||||
|
||||
13. **JSON výstup pro vyhledání kurzu**:
|
||||
```bash
|
||||
python src/cli.py --get-rate 01.01.2025 -c USD --json
|
||||
```
|
||||
|
||||
14. **JSON výstup pro výpočet Jednotného kurzu**:
|
||||
```bash
|
||||
python src/cli.py --stats 2025 -c USD --json
|
||||
```
|
||||
|
||||
## JSON formát
|
||||
|
||||
Při použití přepínače `--json` program vrací strukturovaná data ve formátu JSON:
|
||||
|
||||
### Jednotlivý kurz
|
||||
```json
|
||||
{
|
||||
"currency": "USD",
|
||||
"rate": 24.214,
|
||||
"date": "01.01.2025",
|
||||
"timestamp": "2025-01-12T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Jednotný kurz pro jeden rok
|
||||
```json
|
||||
{
|
||||
"currency": "USD",
|
||||
"year": 2025,
|
||||
"unified_rate": 21.84,
|
||||
"calculation_date": "2025-01-12T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Jednotný kurz pro více let
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"currency": "USD",
|
||||
"rate": 20.632,
|
||||
"date": "31.12.2025",
|
||||
"timestamp": "2025-01-12T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Chyba
|
||||
```json
|
||||
{
|
||||
"error": "Kurz nebyl nalezen",
|
||||
"code": "RATE_NOT_FOUND",
|
||||
"timestamp": "2025-01-12T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user