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)¶

Typ návratové hodnoty:
Parametry:	path (string) – Cesta požadavku args (dict) – Volitelné parametry požadavku
	string

Provede jeden GET API požadavek.

odorik.get_json(path, args=None)¶

Typ návratové hodnoty:
Parametry:	path (string) – Cesta požadavku args (dict) – Volitelné parametry požadavku
	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)¶

Typ návratové hodnoty:
Parametry:	from_date (datetime.datetime) – Počáteční datum to_date (datetime.datetime) – Koncové datum number (string) – Telefonní číslo ve tvaru 00420789123456
	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')¶

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

Odešle SMS zprávu.

odorik.callback(caller, recipient, line=None)¶

Typ návratové hodnoty:
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í.
	string

Objedná zpětné volání.

calls(from_date, to_date, line=None, status=None, direction=None):

Typ návratové hodnoty:
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‘
	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):

Typ návratové hodnoty:
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
	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 program 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.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.

Vítejte v dokumentaci pro Odorik!¶

Python API¶

odorik¶

OdorikException¶

Odorik¶

odorik.config¶

OdorikConfig¶

odorik.main¶

Command¶

Rozhraní Odorik pro příkazovou řádku¶

Použití¶

Popis¶

Globální volby¶

Příkazy¶

Zadávání časového intervalu¶

Soubory¶

Příklady¶

Vývoj¶

Zdrojový kód¶

Sledování chyb¶

Testování¶

Průběžná integrace¶

Změny¶

0.5¶

0.4¶

0.3¶

0.2¶

0.1¶

Rejstříky a tabulky¶

`odorik`¶

`OdorikException`¶

`Odorik`¶

`odorik.config`¶

`OdorikConfig`¶

`odorik.main`¶

`Command`¶