Vítejte v dokumentaci pro Odorik!

Toto je modul pro Python který zpřístupní Odorik API.

Můžete ho nainstalovat z PyPI:

pip install odorik

Projekt je vyvíjen na GitHubu: https://github.com/nijel/odorik

Obsah:

Python API

odorik

OdorikException

exception odorik.OdorikException

Základní třída pro výjimky.

Odorik

Odorik(user='', password='', url=None, config=None):
Parametry:
  • user (string) – ID uživatele
  • password (string) – API heslo
  • url (string) – URL API serveru, pokud není zadáno použije se výchozí
  • config (OdorikConfig) – Objekt s nastaveními, přepíše jakékoliv jiné parametry.

Hlavní třída pro přístup k API. Zadejte uživatele, heslo a volitelně URL API.

odorik.get(path, args=None)
Parametry:
  • path (string) – Cesta požadavku
  • args (dict) – Volitelné parametry požadavku
Typ návratové hodnoty:
 

string

Provede jeden GET API požadavek.

odorik.get_json(path, args=None)
Parametry:
  • path (string) – Cesta požadavku
  • args (dict) – Volitelné parametry požadavku
Typ návratové hodnoty:
 

object

Provede jeden GET API požadavek a zpracuje odpověď ve formátu JSON včetně případného ošetření chyb.

odorik.balance()
Typ návratové hodnoty:
 float

Vrátí aktuální zůstatek.

odorik.mobile_data(from_date, to_date, number=None)
Parametry:
  • from_date (datetime.datetime) – Počáteční datum
  • to_date (datetime.datetime) – Koncové datum
  • number (string) – Telefonní číslo ve tvaru 00420789123456
Typ návratové hodnoty:
 

list

Vrátí využití dat v zadaném časovém intervalu. Volitelně může být filtrován pro zadanou linku.

odorik.send_sms(recipient, message, sender='5517')
Parametry:
  • recipient (string) – Číslo kam odeslat SMS.
  • message (string) – Text zprávy.
  • sender (string) – Volitelné číslo odesílatele.
Typ návratové hodnoty:
 

string

Odešle SMS zprávu.

odorik.callback(caller, recipient, line=None)
Parametry:
  • caller (string) – Číslo, které volá.
  • recipient (string) – Číslo, které se má zavolat.
  • line (string or None) – Jakou linku použít pro vyúčtování.
Typ návratové hodnoty:
 

string

Objedná zpětné volání.

calls(from_date, to_date, line=None, status=None, direction=None):
Parametry:
  • from_date (datetime.datetime) – Počáteční datum
  • to_date (datetime.datetime) – Koncové datum
  • line (string or None) – Jakou linku použít pro výpis
  • status (string) – Stav hovoru, jedno z ‚answered‘, ‚missed‘
  • direction (string) – Směr hovoru, jedno z ‚in‘, ‚out‘, ‚redirected‘
Typ návratové hodnoty:
 

list

Vrátí seznam hovorů v zadaném časovém intervalu. Volitelně může být filtrován pro zadanou linku.

sms(from_date, to_date, line=None):
Parametry:
  • from_date (datetime.datetime) – Počáteční datum
  • to_date (datetime.datetime) – Koncové datum
  • line (string or None) – Jakou linku použít pro výpis
Typ návratové hodnoty:
 

list

Vrátí seznam SMS v zadaném časovém intervalu. Volitelně může být filtrován pro zadanou linku.

odorik.lines()
Typ návratové hodnoty:
 list

Vrátí seznam slovníků s informacemi o linkách.

odorik.config

OdorikConfig

class odorik.config.OdorikConfig(section='odorik')
Parametry:section (string) – Jakou sekci konfiguračního použít

Zpracování konfiguračního souboru podle specifikace XDG.

load(path=None)
Parametry:path (string) – Cesta k souboru s konfigurací.

Načte nastavení z konfiguračního souboru. Pokud není zadána cesta, použije se soubor odorik umístěný v cestě XDG (~/.config/odorik a /etc/xdg/odorik).

odorik.main

odorik.main.main(settings=None, stdout=None, args=None)
Parametry:
  • settings (list of tuples) – vynutit změnu těchto nastavení
  • stdout (file) – výstup pro vypisování textu, pokud není zadáno použije sys.stdout
  • args (list) – parametry z příkazové řádky pro zpracování, pokud není zadáno použije sys.args

Hlavní funkce pro příkazovou řádku.

@odorik.main.register_command(command)

Dekorátor, který registruje třídu Command pro zpracování v parseru funkce main().

Command

class odorik.main.Command(args, config, stdout=None)

Hlavní třída pro spouštění příkazů.

Rozhraní Odorik pro příkazovou řádku

Použití

odorik [parameter] <command> [options]

Jednotlivé příkazy určují jaká operace se provede.

Popis

Tento modul také nainstaluje odorik, který vám ho umožní používat z příkazové řádky.

Globální volby

Program rozumí následujícím globálním volbám. Tyto musí být zadány před příkazem.

--format {csv,json,text,html}

Určí výstupní formát.

--url URL

Nastaví API URL. Přepíše hodnotu z konfiguračního souboru, viz Soubory.

--user USER

Nastaví API uživatele. Přepíše hodnotu z konfiguračního souboru, viz Soubory.

--password PASSWORD

Nastaví API heslo. Přepíše hodnotu z konfiguračního souboru, viz Soubory.

--config PATH

Cesta ke konfiguračnímu souboru, viz Soubory.

--config-section SECTION

Sekce v konfiguračním souboru, viz Soubory.

Příkazy

V současné době jsou k dispozici tyto příkazy:

version

Vypíše verzi programu.

api PATH [--post] [--param KEY=VALUE]...

Provede autentizované volání API. Jako výchozí se použije metoda GET, volbou --post ji změníte na POST.

Další parametry můžete zadat volbou --param, která může být uvedena vícekrát.

balance

Vypíše aktuální zůstatek.

mobile-data [--list] [--phone NUMBER] [--all] [DATE PERIOD]

Vypíše použití mobilních dat.

S parametrem --list vypíše i jednotlivé položky.

Výsledek může být také omezen na telefonní číslo zadáním volby --phone. Telefonní číslo zadávejte ve tvaru 00420789123456.

Pokud použijete volbu --all, program vypíše souhrn pro všechny linky na účtu.

Informace o zadání intervalu dat naleznete v Zadávání časového intervalu.

calls [--list] [--line LINE] [--direction {in,out,redirected}] [--status {answered,missed}] [DATE PERIOD]

Vypíše hovory.

S parametrem --list vypíše i jednotlivé položky.

Výsledek může být také omezen na jednu linku použitím --line.

Hovory dále můžete filtrovat pomocí --status nebo --direction.

Informace o zadání intervalu dat naleznete v Zadávání časového intervalu.

sms [--list] [--line LINE] [DATE PERIOD]

Vypíše SMS zprávy.

S parametrem --list vypíše i jednotlivé položky.

Výsledek může být také omezen na jednu linku použitím --line.

Informace o zadání intervalu dat naleznete v Zadávání časového intervalu.

send-sms [--sender SENDER] recipient message

Odešle SMS zprávu.

Číslo odesílatele můžete změnit pomocí --sender. Musí se jednat o jednu z povolených hodnot. Jako výchozí se použije 5517.

callback [--line LINE] caller recipient

Objedná zpětné volání.

lines [--generate-config]

Vypíše informace o linkách.

S volbou --generate-config tento příkaz vytvoří položky do konfiguračního souboru pro pojmenování linek a telefonních čísel, viz Soubory.

summary [DATE PERIOD]

Vypíše souhrnné informace o všech linkách pod účtem.

Informace o zadání intervalu dat naleznete v Zadávání časového intervalu.

Zadávání časového intervalu

Pro mnoho příkazů můžete zadat časový interval na který se budou aplikovat:

--this-month

Vypíše informace pro tento měsíc. Jedná se o výchozí interval.

--last-month

Vypíše informace pro minulý měsíc.

--start-date DATE

Počáteční datum.

--end-date DATE

Koncové datum. Pokud nebude zadáno použije se aktuální.

Všechny volby zpracují datum nebo čas v téměř jakémkoliv formátu. V dokumentaci k dateutil naleznete podrobnější popis (obzvlášť popis pořadí roku, měsíce a dne).

Soubory

~/.config/odorik
Konfigurační soubor uživatele
/etc/xdg/odorik
Systémový konfigurační soubor

Program dodržuje specifikaci XDG, takže umístění konfiguračních souborů můžete ovlivnit proměnnými prostředí XDG_CONFIG_HOME nebo XDG_CONFIG_DIRS.

Následující parametry mohou být nastaveny v sekci [odorik] (nebo vámi zadané pomocí volby --config-section):

user

API uživatel, může být buď ID uživatele nebo linky.

password

API heslo. Použijte API heslo pro uživatele nebo heslo linky (stejné jako pro SIP) pro přístup na linku.

url

URL API serveru, výchozí je https://www.odorik.cz/api/v1/.

Více informací naleznete na wiki v sekci Autentizace Odorik API.

Konfigurační soubor je ve formátu INI. Například může vypadat takto:

[odorik]
user = pepa
password = zdepa

Dále může konfigurační soubor obsahovat pojmenování pro telefonní čísla a linky:

[lines]
pepa = 12345

[numbers]
pepa = 00420789789789
franta = 00420789123456

Příklady

Vypsat verzi programu:

$ odorik version
version: 0.1

Vypsat aktuální zůstatek:

$ odorik balance
balance: 123.45

Vypsat aktuální využití mobilních dat:

$ odorik mobile-data --phone 00420789123456
bytes_total: 111593707
bytes_down: 87039672
bytes_up: 24554035
price: 0

Odeslání zprávy:

$ odorik send-sms 00420789123456 "Ahoj, jak se mas?"

Objednání zpětného volání:

$ odorik callback 00420789123456 800123456

Výpis souhrnných informací o účtu:

$ odorik summary
Pepa
id: 716000
public_number: 00420789789789
call_count: 58
sms_count: 42
bytes_total: 145921813
data_price: 0.01
call_price: 24.28
sms_price: 12.31
price: 36.59

Franta
id: 717000
public_number: 00420789123456
call_count: 11
sms_count: 0
bytes_total: 0
data_price: 0
call_price: 2.20
sms_price: 0
price: 2.20

Obecné použití API:

$ odorik api sms/allowed_sender
Odorik.cz,5517,00420789123456

Obecné použití POST API:

$ odorik api --post --param caller=00420789123456 --param recipient=800123456 callback

Strojově zpracovatelné výstupní formáty:

$ odorik --format json mobile-data
{
  "bytes_total": 111593707,
  "bytes_down": 87039672,
  "bytes_up": 24554035,
  "price": 0.008
}
$ odorik --format csv mobile-data
bytes_total,111593707
bytes_down,87039672
bytes_up,24554035
price,0.008

Vývoj

Zdrojový kód

Projekt je vyvíjen na GitHubu: https://github.com/nijel/odorik

Sledování chyb

Systém pro sledování chyb je hostován na GitHubu: https://github.com/nijel/odorik/issues

Testování

Testy můžete spustit pomocí py.test.

Průběžná integrace

Pro ověření kvality kódu používáme několik služeb:

Travis CI spouští testy po každé změně
https://travis-ci.org/nijel/odorik
Codecov kontroluje pokrytí kódu testy
https://codecov.io/github/nijel/odorik
Landscape kontroluje kvalitu kódu
https://landscape.io/github/nijel/odorik/master

Změny

0.6

0.5

  • Přeložena dokumentace do češtiny.
  • Podrobnější souhrny pro hovory a zprávy.
  • Přidána možnost filtrovat hovory podle stavu a směru.

0.4

  • Nastavitelné časové intervaly pro příkazy.
  • Přidána podpora pro výpis hovorů.
  • Přidána podpora pro výpis SMS.
  • Přidána podpora pro pojmenování telefonních čísel a linek.
  • Přidán příkaz pro výpis souhrnu stavu účtu.

0.3

  • Přidána podpora pro výpis informací o linkách.
  • Přidána podpora pro výpis využití dat pro všechny linky na účtě.
  • Vylepšené dokumentace.
  • Přidána možnost HTML výstupu.

0.2

  • Vylepšené dokumentace.
  • Přidána podpora pro výstup ve formátu JSON a CSV.
  • Vylepšená podpora pro přímé volání API z příkazové řádky.
  • Parametry z příkazové řádky mohou měnit nastavení z konfiguračního souboru.
  • Přidána podpora pro zpětné volání.

0.1

  • První vydání.
  • Přidána podpora pro výpis využití dat.
  • Přidána podpora pro zjištění zůstatku.
  • Přidána podpora pro posílání zpráv.