nosmsd 0.17

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
- Also add DATABASE_ROUTERS = ['nosmsd.django_routers.NoSMSdRouter'] to
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 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.