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.
Rozhraní Odorik pro příkazovou řádku¶
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.
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 naPOST
.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 tvaru00420789123456
.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žije5517
.
-
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.