parameters: (pgp_d, **kw)
return_statement: return players
docstring: With respect to the API, list useful OpenPGP items.
  
      :Parameters:
          - `pgp_d`: str either ASCII-armored text or native OpenPGP data -
            armored text may contain multiple armored blocks, while native
            OpenPGP data should exist as a single unbroken string
  
      :Keywords:
          - `leftover`: *optional* list to which leftover (non-message)
            packets will be appended - this will include repeats of
            detached or standalone signature packets 
          - `decompress`: set to True to auto-decompress compressed messages
          - `detached`: detached string, signed by signatures in `pgp_d`
  
      :Returns: list of message instances and special signature tuples
  
      This function takes OpenPGP data and returns a list of items that are
      "useful" for the API. In particular, this includes detached, standalone,
      and key signature tuples (hence, "as_signed") which are returned as::
  
          ([det_sig1, det_sig2, ..], string) # detached signatures
          ([key_sig1, key_sig2, ..], key) # key_sigs within a key message
          ([standalone_sig], None) # standalone signature
  
      :note: This is basically a `list_msgs()` which works with armored strings.
          One important difference is that the focus is turned away from packets
          (leftover) toward 'usable things' with respect to the API.
      :note: I'm debating whether or not to scrap the whole ([sigs], target)
          tuple deal and automagically convert detached sigs and clearsigned sigs
          to signed messages, using filename='' and modified='' for both,
          format='b' for detached and format='t' for clearsigned. Higher up, this
          will have the consequence of spitting out the signed stuff (could be a
          lot) with some literal packet header junk prepended. Right now, only
          detached and clearsigned stuff are sent out as tuples. It's just ugly
          worrying about whether we're working with instances or tuples all over
          the place (or ignoring the possibilities and just letting an exception
          be raised).
docstring_summary: With respect to the API, list useful OpenPGP items.
docstring_tokens: With respect to the API list useful OpenPGP items .
function: def list_as_signed(pgp_d, **kw):
      """With respect to the API, list useful OpenPGP items.
  
      :Parameters:
          - `pgp_d`: str either ASCII-armored text or native OpenPGP data -
            armored text may contain multiple armored blocks, while native
            OpenPGP data should exist as a single unbroken string
  
      :Keywords:
          - `leftover`: *optional* list to which leftover (non-message)
            packets will be appended - this will include repeats of
            detached or standalone signature packets 
          - `decompress`: set to True to auto-decompress compressed messages
          - `detached`: detached string, signed by signatures in `pgp_d`
  
      :Returns: list of message instances and special signature tuples
  
      This function takes OpenPGP data and returns a list of items that are
      "useful" for the API. In particular, this includes detached, standalone,
      and key signature tuples (hence, "as_signed") which are returned as::
  
          ([det_sig1, det_sig2, ..], string) # detached signatures
          ([key_sig1, key_sig2, ..], key) # key_sigs within a key message
          ([standalone_sig], None) # standalone signature
  
      :note: This is basically a `list_msgs()` which works with armored strings.
          One important difference is that the focus is turned away from packets
          (leftover) toward 'usable things' with respect to the API.
      :note: I'm debating whether or not to scrap the whole ([sigs], target)
          tuple deal and automagically convert detached sigs and clearsigned sigs
          to signed messages, using filename='' and modified='' for both,
          format='b' for detached and format='t' for clearsigned. Higher up, this
          will have the consequence of spitting out the signed stuff (could be a
          lot) with some literal packet header junk prepended. Right now, only
          detached and clearsigned stuff are sent out as tuples. It's just ugly
          worrying about whether we're working with instances or tuples all over
          the place (or ignoring the possibilities and just letting an exception
          be raised).
      """
      saplog = logging.getLogger("saplog")
      det_d = kw.get('detached', None)
  
      # stringify pgp_d and det_d
      if not pgp_d:
          return [] # det_d requires detached signatures, so it's safe to return
  
      #elif hasattr(pgp_d, 'read'): #elif isinstance(pgp_d, (StringIO, file)):
      #    pgp_d = pgp_d.read()
  
      elif isinstance(pgp_d, str):
          pass
  
      else:
          raise TypeError("Invalid OpenPGP type. Please send string, file, or StringIO.")
  
      if det_d:
          if hasattr(det_d, 'read'):
              det_d = det_d.read()
          elif isinstance(det_d, str):
              pass
          else:
              raise Hell
  
      players = [] # bona fide messages and detached signature tuples
  
      # similar "looks_armored" deal in list_pkts(), perhaps can consolidate
      if looks_armored(pgp_d):
          arm_d = [] # native data
  
          for arm in list_armored(pgp_d):
  
              if 'signed' in arm.__dict__: # distinguished a clearsigned message
  
                  # this is where we can just create a signed message,
                  # literalname = '', modified = 0, format = 't'
  
                  sigs = [p for p in list_pkts(arm.data) if PKT_SIGNATURE == p.tag.type]
                  players.append((sigs, arm.signed))
              else:
                  arm_d.append(arm.data)
  
          pgp_d = ''.join(arm_d)
  
      leftover = []
      msgs = list_msgs(list_pkts(pgp_d), leftover=leftover)
      detached_sigs = []
      detached_types = [SIG_BINARY, SIG_TEXT]
      standalone_types = [SIG_STANDALONE, SIG_TIMESTAMP, SIG_THIRDPARTY]
  
      for pkt in leftover:                            # distinguish leftover..
  
          if PKT_SIGNATURE == pkt.tag.type:
  
              if pkt.body.type in detached_types:     # ..detached sigs from..
                  detached_sigs.append(pkt)
  
              elif pkt.body.type in standalone_types: #..standalone sigs
                  standalone_sigs.append(pkt)
                  players.append(([pkt],None))
  
      if kw.get('decompress'):
  
          for i in range(len(msgs)): 
  
              if MSG_COMPRESSED == msgs[i].type:
                  saplog.info("Decompressing compressed message (%r)." % TXT.alg_comp_msg(msgs[i].compressed.body.alg))
                  compmsg = msgs.pop(i)
                  compplayers = list_as_signed(compmsg.compressed.body.data)
  
                  for j in range(len(compplayers)): # to preserve the order in..
                      msgs.insert(i+j, compplayers[j]) # ..which they appeared
  
      if detached_sigs:
          players.append((detached_sigs, det_d))
  
      players += msgs
  
      if isinstance(kw.get('leftover'), list):
          kw['leftover'].extend(leftover)
  
      return players
function_tokens: def list_as_signed ( pgp_d , * * kw ) : saplog = logging . getLogger ( "saplog" ) det_d = kw . get ( 'detached' , None ) # stringify pgp_d and det_d if not pgp_d : return [ ] # det_d requires detached signatures, so it's safe to return #elif hasattr(pgp_d, 'read'): #elif isinstance(pgp_d, (StringIO, file)): #    pgp_d = pgp_d.read() elif isinstance ( pgp_d , str ) : pass else : raise TypeError ( "Invalid OpenPGP type. Please send string, file, or StringIO." ) if det_d : if hasattr ( det_d , 'read' ) : det_d = det_d . read ( ) elif isinstance ( det_d , str ) : pass else : raise Hell players = [ ] # bona fide messages and detached signature tuples # similar "looks_armored" deal in list_pkts(), perhaps can consolidate if looks_armored ( pgp_d ) : arm_d = [ ] # native data for arm in list_armored ( pgp_d ) : if 'signed' in arm . __dict__ : # distinguished a clearsigned message # this is where we can just create a signed message, # literalname = '', modified = 0, format = 't' sigs = [ p for p in list_pkts ( arm . data ) if PKT_SIGNATURE == p . tag . type ] players . append ( ( sigs , arm . signed ) ) else : arm_d . append ( arm . data ) pgp_d = '' . join ( arm_d ) leftover = [ ] msgs = list_msgs ( list_pkts ( pgp_d ) , leftover = leftover ) detached_sigs = [ ] detached_types = [ SIG_BINARY , SIG_TEXT ] standalone_types = [ SIG_STANDALONE , SIG_TIMESTAMP , SIG_THIRDPARTY ] for pkt in leftover : # distinguish leftover.. if PKT_SIGNATURE == pkt . tag . type : if pkt . body . type in detached_types : # ..detached sigs from.. detached_sigs . append ( pkt ) elif pkt . body . type in standalone_types : #..standalone sigs standalone_sigs . append ( pkt ) players . append ( ( [ pkt ] , None ) ) if kw . get ( 'decompress' ) : for i in range ( len ( msgs ) ) : if MSG_COMPRESSED == msgs [ i ] . type : saplog . info ( "Decompressing compressed message (%r)." % TXT . alg_comp_msg ( msgs [ i ] . compressed . body . alg ) ) compmsg = msgs . pop ( i ) compplayers = list_as_signed ( compmsg . compressed . body . data ) for j in range ( len ( compplayers ) ) : # to preserve the order in.. msgs . insert ( i + j , compplayers [ j ] ) # ..which they appeared if detached_sigs : players . append ( ( detached_sigs , det_d ) ) players += msgs if isinstance ( kw . get ( 'leftover' ) , list ) : kw [ 'leftover' ] . extend ( leftover ) return players