==================
``Policy`` objects
==================


Internally, all policy files generated by this application come from
instances of ``flashpolicies.policies.Policy``, which knows how to
handle the various permitted options in policy files, and can generate
the correct XML. This document covers ``Policy`` objects and their
API, but is not and should not be taken to be documentation on the
format and options for cross-domain policy files; `Adobe's
cross-domain policy specification`_ is the canonical source for that
information.

.. _Adobe's cross-domain policy specification: http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html


Simple interaction with ``Policy`` objects
==========================================

For most cases, simply instantiating a ``Policy`` object with one or
more domains will accomplish the desired effect. The property
``xml_dom`` will yield an ``xml.dom.minidom.Document`` object
representing the policy's XML; for information on working with these
objects, consult the documentation for `the xml.dom.minidom module in
the Python standard library`_. In general, however, the
``toprettyxml()`` method of the ``Document`` will be all that is
required; this serializes the ``Document`` to a string in a particular
encoding, suitable for writing to file or serving via HTTP.

For example::

    >>> from flashpolicies import policies
    >>> my_policy = policies.Policy('media.example.com', 'api.example.com')
    >>> print my_policy.xml_dom.toprettyxml(encoding='utf-8')
    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE cross-domain-policy
      SYSTEM 'http://www.adobe.com/xml/dtds/cross-domain-policy.dtd'>
    <cross-domain-policy>
            <allow-access-from domain="media.example.com"/>
            <allow-access-from domain="api.example.com"/>
    </cross-domain-policy>

.. _the xml.dom.minidom module in the Python standard library: http://docs.python.org/library/xml.dom.minidom.html


Methods of ``Policy`` objects
=============================

The following methods are available on ``Policy`` objects to allow
finer-grained control of the various policy options. For explanations
of what these options mean, please consult the cross-domain policy
specification from Adobe.


``allow_domain(domain, to_ports=None, secure=True)``
----------------------------------------------------

Allow access from ``domain``, which may be either a full domain name,
or a wildcard (e.g., ``*.example.com``, or simply ``*``). Due to
security concerns, it is strongly recommended that you use explicit
domains rather than wildcards.

For socket policy files, pass a list of ports or port ranges as the
keyword argument ``to_ports``. As with ``domain``, a wildcard value --
``*`` -- will allow all ports.

To disable Flash's requirement of security matching (e.g., retrieving
a policy via HTTPS will require that SWFs also be retrieved via
HTTPS), pass ``secure=False``. Due to security concerns, it is
strongly recommended that you not disable this.

``metapolicy(permitted)``
-------------------------

Set meta-policy information (only applicable to master policy
files). Acceptable values correspond to those listed in Section
3(b)(i) of the crossdomain.xml specification, and are also available
as a set of constants defined in this module.

By default, Flash assumes a value of ``master-only``, so if this is
desired (and, for security, it typically is), this method does not
need to be called.

``allow_headers(domain, headers, secure=True)``
-----------------------------------------------

Allow ``domain`` to push data via the HTTP headers named in
``headers``.

As with ``allow_domain``, ``domain`` may be either a full domain name
or a wildcard. Again, use of wildcards is discouraged for security
reasons.

The value for ``headers`` should be a list of header names.
        
To disable Flash's requirement of security matching (e.g., retrieving
a policy via HTTPS will require that SWFs also be retrieved via
HTTPS), pass ``secure=False``. Due to security concerns, it is
strongly recommended that you not disable this.

