Welcome to Odorik’s documentation!¶
This is Python module which wraps Odorik API.
You can install the module from PyPI:
pip install odorik
The project is being developed on GitHub: https://github.com/nijel/odorik
Contents:
Python API¶
odorik
¶
OdorikException
¶
-
exception
odorik.
OdorikException
¶ Base class for all exceptions.
Odorik
¶
-
Odorik(user='', password='', url=None, config=None):
Parameters: - user (string) – User ID
- password (string) – API password
- url (string) – API server URL, if not specified default is used
- config (OdorikConfig) – Configuration object, overrides any other parameters.
Access class to the API, define user, password and optionally API URL.
-
odorik.
get
(path, args=None)¶ Parameters: - path (string) – Request path
- args (dict) – Optional request parameters
Return type: string
Performs single API GET call.
-
odorik.
get_json
(path, args=None)¶ Parameters: - path (string) – Request path
- args (dict) – Optional request parameters
Return type: object
Performs single API GET call and parses JSON reply including error handling.
-
odorik.
balance
()¶ Return type: float Returns current balance.
-
odorik.
mobile_data
(from_date, to_date, number=None)¶ Parameters: - from_date (datetime.datetime) – Starting date
- to_date (datetime.datetime) – Ending date
- number (string) – Phone number in form of 00420789123456
Return type: list
Returns mobile data usage list in given interval. Optionally filtered for given number.
-
odorik.
send_sms
(recipient, message, sender='5517')¶ Parameters: - recipient (string) – Number where to sent SMS.
- message (string) – Text of the message.
- sender (string) – Optional sender number.
Return type: string
Sends a SMS message.
-
odorik.
callback
(caller, recipient, line=None)¶ Parameters: - caller (string) – Number which is calling.
- recipient (string) – Number to call.
- line (string or None) – Line to use for accounting.
Return type: string
Initiates callback.
-
calls(from_date, to_date, line=None, status=None, direction=None):
Parameters: - from_date (datetime.datetime) – Starting date
- to_date (datetime.datetime) – Ending date
- line (string or None) – Line to use for listing
- status (string) – Call status, one of ‘answered’, ‘missed’
- direction (string) – Call direction, one of ‘in’, ‘out’, ‘redirected’
Return type: list
Returns list of calls in given interval. Optionally filtered for given line.
-
sms(from_date, to_date, line=None):
Parameters: - from_date (datetime.datetime) – Starting date
- to_date (datetime.datetime) – Ending date
- line (string or None) – Line to use for listing
Return type: list
Returns list of sms in given interval. Optionally filtered for given line.
-
odorik.
lines
()¶ Return type: list Returns list of dictionaries with information about lines.
odorik.config
¶
OdorikConfig
¶
-
class
odorik.config.
OdorikConfig
(section='odorik')¶ Parameters: section (string) – Configuration section to use Configuration file parser following XDG specification.
-
load
(path=None)¶ Parameters: path (string) – Path where to load configuration. Loads configuration from a file, if none is specified it loads from odorik configuration file placed in XDG configuration path (
~/.config/odorik
and/etc/xdg/odorik
).
-
odorik.main
¶
-
odorik.main.
main
(settings=None, stdout=None, args=None)¶ Parameters: - settings (list of tuples) – settings to override
- stdout (file) – stdout for printing output, uses
sys.stdout
as default - args (list) – command line argumets to process, uses
sys.args
as default
Main entry point for command line interface.
Odorik command line interface¶
Synopsis¶
odorik [parameter] <command> [options]
Commands actually indicate which operation should be performed.
Description¶
This module also installs odorik program, which allows you to easily access some of the functionality from command line.
Global options¶
The program accepts following global options, which must be entered before subcommand.
-
--format
{csv,json,text,html}
¶ Specify output format.
Subcommands¶
Currently following subcommands are available:
-
version
¶
Prints current version.
-
api
PATH [--post] [--param KEY=VALUE]...
¶ Performs authenticated API call. By default
GET
method is used, with--post
it isPOST
.Additional parameters can be specified by
--param
switch which can be used multiple times.
-
balance
¶
Prints current balance.
-
mobile-data
[--list] [--phone NUMBER] [--all] [DATE PERIOD]
¶ Prints mobile data usage.
It can list all individual records when
--list
is specified.The result can be also limited to given phone number by using
--phone
. The phone number has to be specified as00420789123456
.If
--all
is specified, summary for all mobile lines on current account is printed.See Specifying date period for information how to specify date period.
-
calls
[--list] [--line LINE] [--direction {in,out,redirected}] [--status {answered,missed}] [DATE PERIOD]
¶ Prints calls usage.
It can list all individual records when
--list
is specified.The result can be also limited to given line by using
--line
.You can additionally filter calls by
--status
or--direction
.See Specifying date period for information how to specify date period.
-
sms
[--list] [--line LINE] [DATE PERIOD]
¶ Prints SMS usage.
It can list all individual records when
--list
is specified.The result can be also limited to given line by using
--line
.See Specifying date period for information how to specify date period.
-
send-sms
[--sender SENDER] recipient message
¶ Sends a SMS message.
You can specify sender number by
--sender
, it has to be one of allowed values. By default5517
is used.
-
callback
[--line LINE] caller recipient
¶ Initiates a callback.
-
lines
[--generate-config]
¶ Prints infromation about lines.
With
--generate-config
it generates config file entries for line and phone number aliases, see Files.
-
summary
[DATE PERIOD]
¶ Prints summary information for all lines in current account.
See Specifying date period for information how to specify date period.
Specifying date period¶
You can specify date period for which many commands will be issued:
-
--this-month
¶
Prints information for current month. This is the default interval.
-
--last-month
¶
Prints information for last month.
-
--start-date
DATE
¶ Starting datetime.
-
--end-date
DATE
¶ Ending datetime. If not specified, current date is used.
All parameters accepting date can take almost any format of date or timestamp. Check dateutil documentation for more detailed information (especially on year/month/day precendence).
Files¶
~/.config/odorik
- User configuration file
/etc/xdg/odorik
- Global configration file
The program follows XDG specification, so you can adjust placement of config files
by environment variables XDG_CONFIG_HOME
or XDG_CONFIG_DIRS
.
Following settings can be configured in the [odorik]
section (you can
customize this by --config-section
):
-
user
API user, can be either ID registered user or line ID.
-
password
API password. Use API password for per user access and line password (used for SIP as well) for line access.
-
url
API server URL, defaults to
https://www.odorik.cz/api/v1/
.
See Autentizace Odorik API for more details on authentication.
The configuration file is INI file, for example:
[odorik]
user = pepa
password = zdepa
Additionally config file can include phone number and line aliases:
[lines]
pepa = 12345
[numbers]
pepa = 00420789789789
franta = 00420789123456
Examples¶
Print current program version:
$ odorik version
version: 0.1
Print current user balance:
$ odorik balance
balance: 123.45
Prints current mobile data usage:
$ odorik mobile-data --phone 00420789123456
bytes_total: 111593707
bytes_down: 87039672
bytes_up: 24554035
price: 0
Sending message:
$ odorik send-sms 00420789123456 "Ahoj, jak se mas?"
Initiating callback:
$ odorik callback 00420789123456 800123456
Getting account summary:
$ 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
Generic API usage:
$ odorik api sms/allowed_sender
Odorik.cz,5517,00420789123456
Generic API POST:
$ odorik api --post --param caller=00420789123456 --param recipient=800123456 callback
Machine readable output formats:
$ 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
Developing¶
Source code¶
The project is being developed on GitHub: https://github.com/nijel/odorik
Issue tracker¶
Issue tracker is hosted on GitHub: https://github.com/nijel/odorik/issues
Testsuite¶
The testsuite can be executed using py.test
.
Continuous integration¶
We’re using several services to ensure our code is healthy:
- Travis CI for running the testsuite
- https://travis-ci.org/nijel/odorik
- Codecov for reporting the testsuite coverage
- https://codecov.io/github/nijel/odorik
- Landscape for checking quality of our code
- https://landscape.io/github/nijel/odorik/master
Changes¶
0.6¶
0.5¶
- Documentation translated to Czech language.
- More detailed summaries for calls and messages.
- Added options for filtering calls by status and direction.
0.4¶
- Adjustable date periods for commands.
- Add support for listing calls.
- Add support for listing SMS.
- Add support for using names for phone numbers and lines.
- Add summary command to print short overview.
0.3¶
- Added support for listing lines information.
- Added support for listing data usage for all lines on current account.
- Documentation improvements.
- Added html output to the program.
0.2¶
- Documentation improvements.
- Added support for json and csv output.
- Improved command line support for API calls.
- Command line parameters can now override config file.
- Added support for initiating callback.
0.1¶
- Initial release.
- Support for getting data usage.
- Support for getting current balance.
- Support for sending messages.