class_docstr: An incremental decoder that extends Python's built-in UTF-8 decoder.
  
  This encoder needs to take in bytes, possibly arriving in a stream, and
  output the correctly decoded text. The general strategy for doing this
  is to fall back on the real UTF-8 decoder whenever possible, because
  the real UTF-8 decoder is way optimized, but to call specialized methods
  we define here for the cases the real encoder isn't expecting.
class_docstr_tok: ["An","incremental","decoder","that","extends","Python","'s","built-in","UTF-8","decoder",".","This","encoder","needs","to","take","in","bytes",",","possibly","arriving","in","a","stream",",","and","output","the","correctly","decoded","text",".","The","general","strategy","for","doing","this","is","to","fall","back","on","the","real","UTF-8","decoder","whenever","possible",",","because","the","real","UTF-8","decoder","is","way","optimized",",","but","to","call","specialized","methods","we","define","here","for","the","cases","the","real","encoder","is","n't","expecting","."]
docstr: Decode bytes that may be arriving in a stream, following the Codecs
  API.
  
  `input` is the incoming sequence of bytes. `errors` tells us how to
  handle errors, though we delegate all error-handling cases to the real
  UTF-8 decoder to ensure correct behavior. `final` indicates whether
  this is the end of the sequence, in which case we should raise an
  error given incomplete input.
  
  Returns as much decoded text as possible, and the number of bytes
  consumed.
docstr_tok: ["Decode","bytes","that","may","be","arriving","in","a","stream",",","following","the","Codecs","API",".","`","input","`","is","the","incoming","sequence","of","bytes",".","`","errors","`","tells","us","how","to","handle","errors",",","though","we","delegate","all","error-handling","cases","to","the","real","UTF-8","decoder","to","ensure","correct","behavior",".","`","final","`","indicates","whether","this","is","the","end","of","the","sequence",",","in","which","case","we","should","raise","an","error","given","incomplete","input",".","Returns","as","much","decoded","text","as","possible",",","and","the","number","of","bytes","consumed","."]
code: def _buffer_decode(self, input, errors, final):
      """
      Decode bytes that may be arriving in a stream, following the Codecs
      API.
  
      `input` is the incoming sequence of bytes. `errors` tells us how to
      handle errors, though we delegate all error-handling cases to the real
      UTF-8 decoder to ensure correct behavior. `final` indicates whether
      this is the end of the sequence, in which case we should raise an
      error given incomplete input.
  
      Returns as much decoded text as possible, and the number of bytes
      consumed.
      """
      # decoded_segments are the pieces of text we have decoded so far,
      # and position is our current position in the byte string. (Bytes
      # before this position have been consumed, and bytes after it have
      # yet to be decoded.)
      decoded_segments = []
      position = 0
      while True:
          # Use _buffer_decode_step to decode a segment of text.
          decoded, consumed = self._buffer_decode_step(
              input[position:], errors, final
          )
          if consumed == 0:
              # Either there's nothing left to decode, or we need to wait
              # for more input. Either way, we're done for now.
              break
  
          # Append the decoded text to the list, and update our position.
          decoded_segments.append(decoded)
          position += consumed
  
      if final:
          # _buffer_decode_step must consume all the bytes when `final` is
          # true.
          assert position == len(input)
  
      return "".join(decoded_segments), position
  
file_path: python-ftfy/ftfy/bad_codecs/utf8_variants.py
imports: import re
  import codecs
  from typing import Tuple
  from encodings.utf_8 import IncrementalDecoder, IncrementalEncoder
label_desc: Use image node_id 1 for calling the IncrementalDecoder obj's underlying member method code with example usage: obj._buffer_decode(input, errors, final) and returns: str,  position