= 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 +33198765432
        $ /path/to/env/bin/nosmsd_sendout.py '+22377667766' "Hello world"

    * I want to test my handler / simulate an incoming SMS
        $ /path/to/env/bin/nosmsd_inject.py '+22366908765' "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('+22377667766', 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.