API Documentation
=================

.. _optional_settings:

Optional Settings
-----------------

The following optional settings can go into ``settings.py`` to change the
functionality of RPC4Django

.. envvar:: RPC4DJANGO_LOG_REQUESTS_RESPONSES 

    By default RPC4Django will log (using the python logging module) all 
    requests and responses. This can be disabled by setting this to ``False``.
    
.. envvar:: RPC4DJANGO_RESTRICT_INTROSPECTION      
    
    By default RPC4Django registers the standard XMLRPC and JSONRPC 
    introspection functions. This can be disabled by setting this to ``True``.

.. envvar:: RPC4DJANGO_RESTRICT_JSONRPC   
    
    If ``True``, RPC4Django will never serve a JSONRPC request. 
    Instead, either XMLRPC will be tried or status code 404 will be returned.
    Defaults to ``False``.
    
.. envvar:: RPC4DJANGO_RESTRICT_XMLRPC    
    
    If ``True``, RPC4Django will never serve 
    an XMLRPC request. Instead, either JSONRPC will be tried or status 
    code 404 will be returned. Defaults to ``False``.
    
.. envvar:: RPC4DJANGO_RESTRICT_METHOD_SUMMARY
    
    If ``True``, status code 404 will be returned instead of serving the 
    method summary as a response to a GET request. Defaults to ``False``.
    
.. envvar:: RPC4DJANGO_RESTRICT_RPCTEST
    
    If ``True``, the method summary will not allow testing via JSONRPC from
    the generated method summary page. Defaults to ``False``

.. envvar:: RPC4DJANGO_RESTRICT_REST
    
    If ``True``, RPC4Django does not attempt to 
    convert any of the method summary docstrings to restructured text.
    Defaults to ``False``.
    
.. envvar:: RPC4DJANGO_RESTRICT_OOTB_AUTH

    If ``False``, enables out of the box authentication via the RPC methods
    :meth:`system.login <rpc4django.rpcdispatcher.RPCDispatcher.system_login>` and
    :meth:`system.logout <rpc4django.rpcdispatcher.RPCDispatcher.system_logout>`.
    Out of the box authentication should NOT be considered secure
    when used without SSL or TLS.
    Defaults to ``True``.
    
.. envvar:: RPC4DJANGO_HTTP_ACCESS_CREDENTIALS
    
    If ``True``, RPC4Django will respond to OPTIONS requests with the HTTP header 
    ``Access-Control-Allow-Credentials`` set to the given value. This pertains 
    to allowing cross site requests with cookies. See the Mozilla documentation 
    on `requests with credentials`_ for more details. Defaults to ``False``.

.. envvar:: RPC4DJANGO_HTTP_ACCESS_ALLOW_ORIGIN

    RPC4Django will respond to OPTIONS requests with the HTTP header 
    ``Access-Control-Allow-Origin`` set to the given value. This pertains to 
    allowing cross site requests. See the Mozilla documentation on 
    `preflighted requests`_ for more details. Defaults to the empty string.

.. envvar:: RPC4DJANGO_JSON_ENCODER

    Subclass of ``rpc4django.jsonrpcdispatcher.json.JSONEncoder`` or string
    pointing to the subclass. It can be used to serialize objects that can't
    otherwise be serialized. Defaults to
    ``django.core.serializers.json.DjangoJSONEncoder``.

.. _requests with credentials: https://developer.mozilla.org/en/HTTP_access_control#Requests_with_credentials
.. _preflighted requests: https://developer.mozilla.org/en/HTTP_access_control#Preflighted_requests

