xsacha bar files

Specialization of |Properties| and |Section| for BAR Manifest Files
(:file:`META-INF/MANIFEST.MF`) and BlackBerry Resource Files
(:file:`META-INF/{locale}.bbr`).

The format of BAR Manifest Files and of BlackBerry Resource Files is
specified in the |BAR| specification.  The manifest contains meta-data
describing the content of the BAR file; the BBR files contain
localized versions of some of this meta-data.

One design goal for this version of the code is that it be robust in
the face of future |BAR| specifications.  It accomplishes this largely
by being as insensitive as possible to sections and attributes which
it doesn't need to understand.

One useful consequence of this design decision is that no separate
implemetation is needed for BlackBerry Resource (BBR) Files, which are
structurally identical to a manifest file (with the sole exception of
the additional attribute :barattr:`Entry-Point-Localization`).  As a
result, although a BBR is only permitted in actuality to contain a
subset of the attributes allowed in the full manifest, the same
implementation serves for both.

.. |BarSection| replace:: :class:`~deckard.bar.manifest.BarSection`
s���restructuredtext enu-���Neil Schellenberger <nschellenberger@qnx.com>uF���Copyright 2010, 2011, 2012, QNX Software Systems. All Rights Reserved.s���3.1.0t���BarManifestt
���BarSectioniÿÿÿÿN(���t���BarAssetUnknownErrort���BarFileLimitErrort���BarPropertiesSyntaxErrort���BarPropertiesSemanticError(���t���Sectiont
���Propertiest���PropertiesError(
���t���Digests(
���t���asboolc�����������B���s5���e��Z
�d��Z�d
����Z�e�d�����
�Z�e�d�����
�Z�RS(���s��
    A specialization of |Section| for |BAR| Manifest Files.

    Version 1.4 of the |BAR| specification states that a Manifest File
    may contain a variety of sections: 'Archive', 'Package',
    'Application', 'Entry-Point', 'System', 'Debug-Token', 'Patch',
    and 'Archive-Asset'.

    The 'Archive' section contains mostly meta-data about the manifest
    itself.

    The 'Package' section contains attributes describing the BAR as a
    whole.  The :barattr:`Package-Id` is guaranteed to be unique to
    this :barattr:`Package-Author-Id` and :barattr:`Package-Name`.

    The 'Patch' section appears only if the :barattr:`Package-Type` is
    ``patch``.  It contains meta-information about the patch,
    including the effective package type,
    :barattr:`Patch-Package-Type`.  The effective package type for
    non-patch packages is just the value of :barattr:`Package-Type`.

    The 'Application' section only appears if the effective package
    type is ``application``.  The :barattr:`Application-Id` is
    guaranteed to be unique to this :barattr:`Package-Id`.  An
    application may specify that it is to be installed in development
    mode (which has relaxed security), this is governed by the
    :barattr:`Application-Developer-Mode` attribute, which defaults to
    false.

    The 'System' section only appears if the effective package type is
    ``system``.  It represents an operating system or radio package.

    The 'Debug-Token' section only appears if the
    :barattr:`Package-Type` is ``debug-token`` (debug tokens cannot be
    patched).

    'Entry-Point` sections only appear if the effective package type
    is ``application``.  Currently the system only actually supports
    one entry point per application; the last one specified wins.  In
    older versions of the |BAR| specification, application
    capabilities were undifferentiated between system and user actions
    and were all specified at the start of the value of the
    :barattr:`Entry-Point` attribute in the form
    :samp:``[cap1,cap2,cap3]`; this form continues to be supported for
    backward compatibility, with the sole exception of the deprecated
    capabilities ``autoorient``, ``portrait``, and ``landscape``.
    Newer versions of manifest have
    :barattr:`Entry-Point-User-Actions` and
    :barattr:`Entry-Point-System-Actions` instead.  (The old form is
    ignored if the new form is present.)

    The 'Archive-Asset' sections describe each ''asset'' in the BAR.
    An ''asset'' is defined to be any file (not directory) in the BAR
    which is not :file:`META-INF/{*.MF,SF,EC}` (i.e. signing related).
    A check for this is implemented as :meth:`is_exempt`.  THe
    |BARSIGN| specification requires that each asset must have one or
    more digests listed for it.

    .. inheritance-diagram:: BarSection
    c���������C���sD���|�r'�|
�d
�k�r'�|�j��d�d���}�n��t
�t�|����j�|
�|���
d�S(���s�
        Set the attribute `name` to `value` using the current locale.

        :param name: The mapping key to be set.
        :param value: The value to which the key is to be set.

        The :meth:`~deckard.util.properties.Section.__setitem__`
        behaviour is specialized for BAR Manifest Files in only one
        respect: the asset names are normalized to use the POSIX path
        separator.

        .. rubric:: Implementation Notes

        It has historically been the case that BAR files generated
        and/or signed on Windows hosts have sometimes used the Windows
        path separator.  (Although that may have been a tooling bug.)
        The |BARSIGN| specification does not make it clear which, if
        any, is correct.  Accordingly, we do not reject the use of
        Windows path separators as an error.

        However, since the asset names are typically used as ZIP
        archive member names or as POSIX relative path names in the
        code, it is far more convenient to normalize them once here at
        the source than to force all potential clients to deal with
        the possiblity.

        Obviously, this also precludes legitimate use of the backslash
        as an asset name character (a usage forbidden neither by
        |BARSIGN| nor POSIX).  However, this is probably best viewed
        as a feature.

        >>> s = BarSection()
        >>> s['Archive-Asset-Name'] = r'foo\bar'
        >>> s['Archive-Asset-Name']
        'foo/bar'
        s���Archive-Asset-Names
���\t
���/N(���t���replacet���superR
���t���__setitem__(���t���selft���namet���value(����(����s8���/usr/lib/python2.7/site-packages/deckard/bar/manifest.pyR���q���s����%

c
���
������C���s���d
�|��k�r�d
�St��j
�|���
�S(���s��
        Guess the kind from the sequence of `keys` provided.

        :param keys: A sequence of key names.
        :type keys: sequence of |str|
        :returns: The 'kind' inferred from the `keys`.
        :rtype: |str| or |None|

        The empty string may be returned if there is no common prefix
        among the `keys`.  |None| will be returned if no `keys` are
        provided.

        .. compound::

            The value returned depends on `keys`:

                1. if they include :barattr:`Entry-Point`, then
                   'Entry-Point' is returned (because if that were the
                   only key, the default guess would be just 'Entry');
                   otherwise
                2. the default guess from |Section.guesskind| is
                   returned.

        >>> BarSection.guesskind(['Entry-Point'])
        'Entry-Point'
        >>> BarSection.guesskind(['Entry-Point-Name'])
        'Entry-Point'
        >>> BarSection.guesskind(['Application-Name'])
        'Application'
        s���Entry-Point(���R���t	���guesskind(
���t���keys(����(����s8���/usr/lib/python2.7/site-packages/deckard/bar/manifest.pyR�������s���� 

c���������C���s?���|
�d
�d�d�d�d�h�k�r�d�Sd�|��k�r/�d�St
�j�|��|
���S(���s�	��
        Guess the name of the key attribute from the `kind` and the
        sequence of `keys` provided; the result will either be one of
        the `keys` or |None|.

        :param keys: A sequence of key names.
        :type keys: sequence of |str|
        :param kind: The kind of keys.
        :type kind: |str| or |None|
        :returns: The 'key' inferred from the `kind` and `keys`.
        :rtype: |str| or |None|

        .. compound::

            The value returned is governed by `kind` and `keys`:

                1. if the `kind` is known not to have a key attribute,
                   then |None| is returned; or
                2. if the `keys` include
                   :barattr:`Entry-Point-Localization`, then
                   :barattr:`Entry-Point-Localization` is returned;
                   otherwise
                3. the default guess from |Section.guesskind| is
                   returned.

        The first rule is primarily to arrange for 'Package' and
        'Application' sections to be treated anonymously (despite
        having :barattr:`Package-Name` and :barattr:`Application-Name`
        attributes respectively).  This is not really functionally
        important since they are singletons anyway, but it does ensure
        that this, like all other singleton sections, are stored
        anonymously for consistency.  The other cases listed
        ('System', 'Debug-Token', and 'Patch') are only present as an
        optimzation since we were checking anyway; the default guess
        would have made the right choice anyway.  For the purpose of
        this method itself, it is not necessary that the list be kept
        perfectly in sync with new |BAR| specifications (unless it is
        necessary for other reasons).

        The second rule handles the case of BBR localization files
        which use :barattr:`Entry-Point-Localization` as the key to
        match against :barattr:`Entry-Point-Name` in the manifest
        (while the BBR :barattr:`Entry-Point-Name` provides the locale
        specific value).



    A specialization of |Properties| for BAR Manifest and BlackBerry
    Resource Files.

    This class extends |Properties| with some methods which relate
    directly to BAR manifest handling.  These are convenience methods
    for accessing various attributes, chiefly ones related to the
    'Archive-Assets' sections.

    .. rubric:: Localization

    A BAR for which the manifest specifies :barattr:`Package-Locales`
    is expected to contain a BBR file for each named locale.  These
    BBR files contain localized versions of particular attributes
    (:barattr:`Application-Name` and so on).

    In particular, 'Entry-Point` sections can be localized.  Because
    they are named sections, it is necessary to match the each BBR
    'Entry-Point' section with its correct manifest counterpart.  The
    key in the manifest is :barattr:`Entry-Point-Name` (which also
    provides the default, unlocalized value); the key in the BBR is
    :barattr:`Entry-Point-Localization`, while
    :barattr:`Entry-Point-Name` provides the localized value.

    This is handled by :meth:`BarSection.guesskey`, which arranges to
    return :barattr:`Entry-Point-Name` as the key for manifest
    sections, but :barattr:`Entry-Point-Localization` for BBR
    sections.  Thus, when localized by entry point section name, each
    BBR 'Entry-Point' section is merged with its correct associated
    manifest 'Entry-Point' section.

    .. rubric:: Implementation Notes

    This is actually really only of theoretical interest at the moment
    since only a single 'Entry-Point' is actually supported.  However,
    properly handling this case provides an oppportunity to catch
    mismatches; a full implementation is also hopefully futureproof as
    well, at least at this level.

    .. inheritance-diagram:: BarManifest
    s"