nosmsd 0.2

Python wrapper around Gammu-smsd Database.

= NoSMSd =

NoSMSd is a python wrapper around the Gammu-smsd Database.
It allows one to easily setup Gammu-smsd and interact with it from python.

It's moto is to let Gammu do all the work. It's a wrapper, not a framework.

Dependences:
* peewee (pip install peewee)
* Any database connector you might need.
Beware that it's been tested only on MySQL.

Installation:
pip install nosmsd

* Django Integration

NoSMSd does _NOT_ require django.

Still, if you are using it server-side and you are already using django,
you can benefit from the following features:
- a management command for processing incoming SMS
./manage.py nosmsd_incoming 3
This will allow you to access you django models & other from your
SMS handler.
- Django Admin integration: you can view your received and sent messages
right from the django admin.
- Add a database named 'smsd' for your NoSMSd schema and 'nosmsd' in the
INSTALLED_APPS in your django settings.py

* Warnings
- Gammu is not expecting third parties to mess-around with its DB.
You should not attempt to write to Django Model.
It is disabled on purpose. If Gammu encounters a MySQL error (like a
pk error on the sentitems table with have two pk), it will freeze.


Example Use:

* Setting-up Gammu
Please note that NoSMSd Gammu assumes you have a working Gammu-smsd setup.
NoSMSd itself does only rely on its Database so you can do anything
without Gammu but you'll eventually need it.
You can find an example gammu-smsdrc in the contrib/ folder.

* Database schema
NoSMSd is using the Gammu SQL schema with a small addition to the Inbox
Table.
Create your tables with provided script in contrib/ or use the alter
statement also available if you already have a working Gammu.

* Settings
If you only want to send out SMS, you don't need to configure anything.
If you want to receive, you need to specify your message handler with
NOSMSD_HANDLER. It is the full module.function path to your handler.
Configure it by creating a python module in one of the following locations:
- /etc/nosmsd.conf.py
- ~/.nosmsd.conf.py
- ~/nosmsd.conf.py
- nosmsd.conf.py
You can overwrite any of the existing config vars in the settings.py module.
You can find an example in the contrib/ folder.

* I want to send a message to number [phone]
$ /path/to/env/bin/nosmsd_sendout.py '[phone]' "Hello world"

* I want to test my handler / simulate an incoming SMS
$ /path/to/env/bin/nosmsd_inject.py '[phone]' "weather in bamako?"

* How do I configure Gammu to process SMS in Python?
In your gammu-smsdrc file, configure the RunOnReceive directive
RunOnReceive = /path/to/env/bin/nosmsd_incoming.py

If you are using a virtualenv, there's a convenient script to help you
RunOnReceive = /path/to/env/bin/nosmsd_incoming_venv.py
You will need to set NOSMSD_VENV_PATH to the full path of your VENV.

If you are using Django and want to access django features from within
your handler, add NoSMSd to your django settings then use the following:
RunOnReceive = /path/to/djangoproj/manage.py nosmsd_incoming

* I want to send an SMS from Python
from nosmsd.utils import send_sms
send_sms('[phone]', u"صباح الخير")

* How do I write a handler?
A handler is a regular function accepting a single parameter: message.
message is a database.Inbox message with the following (notable) fields:
- date
- content
- identity (the sender number
- status
- respond(text) method to reply directly.