API Reference
*************


Main Functions
==============

htmlmin.minify(input, remove_comments=False, remove_empty_space=False, remove_all_empty_space=False, reduce_empty_attributes=True, reduce_boolean_attributes=False, remove_optional_attribute_quotes=True, convert_charrefs=True, keep_pre=False, pre_tags=('pre', 'textarea'), pre_attr='pre', cls=<class 'htmlmin.parser.HTMLMinParser'>)

   Minifies HTML in one shot.

   Parameters:
      * **input** -- A string containing the HTML to be minified.

      * **remove_comments** --

        Remove comments found in HTML. Individual comments can be
        maintained by putting a "!" as the first character inside the
        comment. Thus:

           <!-- FOO --> <!--! BAR -->

        Will become simply:

           <!-- BAR -->

        The added exclamation is removed.

      * **remove_empty_space** -- Remove empty space found in HTML
        between an opening and a closing tag and when it contains a
        newline or carriage return. If whitespace is found that is
        only spaces and/or tabs, it will be turned into a single
        space. Be careful, this can have unintended consequences.

      * **remove_all_empty_space** -- A more extreme version of
        "remove_empty_space", this removes all empty whitespace found
        between tags. This is almost guaranteed to break your HTML
        unless you are very careful.

      * **reduce_boolean_attributes** -- Where allowed by the HTML5
        specification, attributes such as 'disabled' and 'readonly'
        will have their value removed, so 'disabled="true"' will
        simply become 'disabled'. This is generally a good option to
        turn on except when JavaScript relies on the values.

      * **remove_optional_attribute_quotes** -- When True, optional
        quotes around attributes are removed. When False, all
        attribute quotes are left intact. Defaults to True.

      * **conver_charrefs** -- Decode character references such as
        &amp; and &#46; to their single charater values where safe.
        This currently only applies to attributes. Data content
        between tags will be left encoded.

      * **keep_pre** -- By default, htmlmin uses the special attribute
        "pre" to allow you to demarcate areas of HTML that should not
        be minified. It removes this attribute as it finds it. Setting
        this value to "True" tells htmlmin to leave the attribute in
        the output.

      * **pre_tags** -- A list of tag names that should never be
        minified. You are free to change this list as you see fit, but
        you will probably want to include "pre" and "textarea" if you
        make any changes to the list. Note that "<script>" and
        "<style>" tags are never minimized.

      * **pre_attr** -- Specifies the attribute that, when found in an
        HTML tag, indicates that the content of the tag should not be
        minified. Defaults to "pre". You can also prefix individual
        tag attributes with  "{pre_attr}-" to prevent the contents of
        the individual attribute from being changed.

   Returns:
      A string containing the minified HTML.

   If you are going to be minifying multiple HTML documents, each with
   the same settings, consider using "Minifier".

class htmlmin.Minifier(remove_comments=False, remove_empty_space=False, remove_all_empty_space=False, reduce_empty_attributes=True, reduce_boolean_attributes=False, remove_optional_attribute_quotes=True, convert_charrefs=True, keep_pre=False, pre_tags=('pre', 'textarea'), pre_attr='pre', cls=<class 'htmlmin.parser.HTMLMinParser'>)

   An object that supports HTML Minification.

   Options are passed into this class at initialization time and are
   then persisted across each use of the instance. If you are going to
   be minifying multiple peices of HTML, this will be more efficient
   than using "htmlmin.minify".

   See "htmlmin.minify" for an explanation of options.

   minify(*input)

      Runs HTML through the minifier in one pass.

      Parameters:
         **input** -- HTML to be fed into the minimizer. Multiple
         chunks of HTML can be provided, and they are fed in
         sequentially as if they were concatenated.

      Returns:
         A string containing the minified HTML.

      This is the simplest way to use an existing "Minifier" instance.
      This method takes in HTML and minfies it, returning the result.
      Note that this method resets the internal state of  the parser
      before it does any work. If there is pending HTML in the
      buffers, it will be lost.

   input(*input)

      Feed more HTML into the input stream

      Parameters:
         **input** -- HTML to be fed into the minimizer. Multiple
         chunks of HTML can be provided, and they are fed in
         sequentially as if they were concatenated. You can also call
         this method multiple times to achieve the same effect.

   property output

      Retrieve the minified output generated thus far.

   finalize()

      Finishes current input HTML and returns mininified result.

      This method flushes any remaining input HTML and returns the
      minified result. It resets the state of the internal parser in
      the process so that new HTML can be minified. Be sure to call
      this method before you reuse the "Minifier" instance on a new
      HTML document.


WSGI Middlware
==============

class htmlmin.middleware.HTMLMinMiddleware(app, by_default=True, keep_header=False, debug=False, **kwargs)

   WSGI Middleware that minifies html on the way out.

   Parameters:
      * **by_default** -- Specifies if minification should be turned
        on or off by default. Defaults to "True".

      * **keep_header** -- The middleware recognizes one custom HTTP
        header that  can be used to turn minification on or off on a
        per-request basis: "X-HTML-Min-Enable". Setting the header to
        "true" will turn minfication on; anything else will turn
        minification off. If "by_default" is set to  "False", this
        header is how you would turn minification back on. The
        middleware, by default, removes the header from the output.
        Setting this to "True" leaves the header in tact.

      * **debug** -- A quick setting to turn all minification off. The
        middleware is effectively bypassed.

   This simple middleware minifies any HTML content that passes
   through it. Any additional keyword arguments beyond the three
   settings the middleware has are passed on to the internal minifier.
   The documentation for the options can be found under
   "htmlmin.minify".


Decorator
=========

htmlmin.decorator.htmlmin(*args, **kwargs)

   Minifies HTML that is returned by a function.

   A simple decorator that minifies the HTML output of any function
   that it decorates. It supports all the same options that
   "htmlmin.minify" has. With no options, it uses "minify"'s default
   settings:

      @htmlmin
      def foobar():
         return '   minify me!   '

   or:

      @htmlmin(remove_comments=True)
      def foobar():
         return '   minify me!  <!-- and remove me! -->'
