=====
Usage
=====
Typically, you import :mod:`smartypants` and call the
:func:`smartypants.smartypants` to convert a text, for example:
.. code:: python
import smartypants
text = '"SmartyPants" is smart, so is smartypants.py
-- a Python port'
print(smartypants.smartypants(text))
It results::
“SmartyPants” is smart, so is smartypants.py
— a Python port
Attributes
==========
:func:`smartypants.smartypants` accepts processing attributes, which tells it
what need to be converted.
.. seealso:: :class:`smartypants.Attr ` for a list of attributes.
To use these attributes, simply using bitwise *OR* operator, that is ``A | B``:
.. code:: python
from smartypants import Attr
attrs = Attr.q | Attr.d
smartypants.smartypants(text, attrs)
attrs = Attr.set1 | Attr.w
smartypants.smartypants(text, attrs)
.. _skip-html:
Skipped HTML elements
=====================
Elements
--------
By default, there are a few HTML elements that :func:`smartypants.smartypants`
do not try to be smart with them:
.. code:: python
tags_to_skip = ['pre', 'samp', 'code', 'tt', 'kbd', 'script', 'style', 'math']
If you need to change, for example, adding additional tags and remove one of
them:
.. code:: python
>>> from smartypants import tags_to_skip as tags
>>> tags.append('a')
>>> tags.remove('code')
>>> tags
['pre', 'samp', 'tt', 'kbd', 'script', 'style', 'math', 'a']
The :attr:`smartypants.tags_to_skip` is compiled into a regular expression for
being used by :func:`smartypants.smartypants`. You could actually overwrite
:func:`smartypants._tags_to_skip_regex` and return with your own regular
expression.
Comments
--------
HTML comments are always skipped since they are not rendered in browsers.
.. code:: python
>>> from smartypants import smartypants as sp
>>> print(sp(''))
.. important::
Beware of ``--``, which should not or must not be in a HTML comment.
.. code:: python
>>> from smartypants import smartypants as sp
>>> print(sp(''))
”foo—bar” —>
Backslash escapes
=================
If you need to use literal straight quotes (or plain hyphens and periods), for
example, text like ``6'2"`` may become ``6‘2”``. To avoid such situation,
you can use backslash escapes like ``6\'2\"``.
.. seealso:: :func:`smartypants.process_escapes` for a complete list of backslash escapes.