fa.apps
=======

.. module:: fa.apps

The apps module contains classes and functions that deal with FoneAstra apps,
which enable a Django app to be discoverable by the FoneAstra framework and
facilitate communication between FoneAstra devices and the server.

.. class:: FoneAstraApp

   This is the core app that all FoneAstra apps should subclass. This class also
   includes extra methods and fields for interfacing with FoneAstra, and
   FoneAstra autodiscovery only includes apps that subclass :py:class:`~fa.apps.FoneAstraApp`.

Attributes and methods to override in subclasses
------------------------------------------------

.. attribute:: FoneAstraApp.app_name

   This should be the name of the app. For instance, an application designed
   for use in a milk bank should set :py:attr:`~fa.apps.FoneAstraApp.app_name`
   to "Milk Bank" in its subclass.
   
   Example::
   
      app_name = "Milk Bank"

.. attribute:: FoneAstraApp.app_index

   The app's index view, as a reverse name. Override this in subclasses.

   Example::

      app_index = "mb_index"

.. attribute:: FoneAstraApp.device_types

   An iterable of class objects in this app that subclass
   :py:class:`~fa.models.FoneAstraDevice`. Only devices with their type listed
   in this iterable will have their instance receive method called when they
   send a message to the server.

   Example::

      from mb.models import MilkBankDevice
      device_types = (MilkBankDevice,)

.. classmethod:: FoneAstraApp.receive(cls, msg)

   This method gets called if a message arrives that did not come from any
   registered FoneAstra device in any app. This method is most frequently
   called for configuration messages.

   :param fa.models.IncomingMessage msg: The incoming message.

Convenience methods
-------------------

.. classmethod:: FoneAstraApp.find_all_fa_apps(cls)

   Returns all FoneAstraApp subclasses defined in all apps in
   *INSTALLED_APPS*.

.. classmethod:: FoneAstraApp.get_device(cls, phone_number)

   Returns the FoneAstra device with the given phone number and with a type
   contained in :py:attr:`~fa.apps.FoneAstraApp.device_types`, or *None* if no
   such device exists.

   :param string phone_number: The phone number corresponding to the device.