OS Manuals

smartypants(1)

smartypants - smartypants Documentation

SMARTYPANTS(1) smartypants SMARTYPANTS(1)

smartypants - smartypants Documentation

Contents:

smartypants <https://github.com/justinmayer/smartypants.py> is a Python fork of SmartyPants <http://daringfireball.net/projects/smartypants/>.

smartypants can perform the following transformations:

  • Straight quotes (" and ') into “curly” quote HTML entities
  • Backticks-style quotes (``like this'') into “curly” quote HTML entities
  • Dashes (-- and ---) into en- and em-dash entities
  • Three consecutive dots (... or . . .) into an ellipsis entity

This means you can write, edit, and save your posts using plain old ASCII straight quotes, plain dashes, and plain dots, but your published posts (and final HTML output) will appear with smart quotes, em-dashes, and proper ellipses.

smartypants does not modify contents in some HTML element, see Skipped HTML Elements <#skip-html>. Typically, these tags are used to display text where smart quotes and other "smart punctuation" would not be appropriate, such as source code or example markup.

To use it as a module:

import smartypants
text = '"SmartyPants" is smart, so is <code>smartypants</code> -- a Python port'
print(smartypants.smartypants(text))


To use the command-line script smartypants:

echo '"SmartyPants" is smart, so is <code>smartypants</code> -- a Python port' | smartypants


Both produce:

&#8220;SmartyPants&#8221; is smart, so is <code>smartypants</code> &#8212; a Python port


smartypants package on PyPI <https://pypi.python.org/pypi/smartypants/> can be installed via pip:

python -m pip install smartypants


If you want to install latest development code, you can run:

python -m pip install git+https://github.com/justinmayer/smartypants.py


Typically, you import smartypants <#module-smartypants> and call the smartypants.smartypants() <#smartypants.smartypants> to convert a text, for example:

import smartypants
text = '"SmartyPants" is smart, so is <code>smartypants.py</code> -- a Python port'
print(smartypants.smartypants(text))


It results:

&#8220;SmartyPants&#8221; is smart, so is <code>smartypants.py</code> &#8212; a Python port


smartypants.smartypants() <#smartypants.smartypants> accepts processing attributes, which tells it what need to be converted.

See also:

smartypants.Attr <#smartypants._Attr> for a list of attributes.


To use these attributes, simply using bitwise OR operator, that is A | B:

from smartypants import Attr
attrs = Attr.q | Attr.d
smartypants.smartypants(text, attrs)
attrs = Attr.set1 | Attr.w
smartypants.smartypants(text, attrs)


By default, there are a few HTML elements that smartypants.smartypants() <#smartypants.smartypants> do not try to be smart with them:

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:

>>> from smartypants import tags_to_skip as tags
>>> tags.append('a')
>>> tags.remove('code')
>>> tags
['pre', 'samp', 'tt', 'kbd', 'script', 'style', 'math', 'a']


The smartypants.tags_to_skip <#smartypants.tags_to_skip> is compiled into a regular expression for being used by smartypants.smartypants() <#smartypants.smartypants>. You could actually overwrite smartypants._tags_to_skip_regex() <#smartypants._tags_to_skip_regex> and return with your own regular expression.

HTML comments are always skipped since they are not rendered in browsers.

>>> from smartypants import smartypants as sp
>>> print(sp('<!-- <span>"foobar"</span> -->'))
<!-- <span>"foobar"</span> -->


Important:

Beware of --, which should not or must not be in a HTML comment. 

>>> from smartypants import smartypants as sp
>>> print(sp('<!-- <span>"foo--bar"</span> -->'))
<!&#8212; <span>&#8221;foo&#8212;bar&#8221;</span> &#8212;>




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\".

See also:

smartypants.process_escapes() <#smartypants.process_escapes> for a complete list of backslash escapes.


smartypants <https://github.com/justinmayer/smartypants.py> is hosted on GitHub. You can clone the repository or file an issue report from there.

You are welcome to contribute whatever you can. Coding, documenting, reporting issues, requesting features, even correcting typos.

If you want to contribute to the source code, be sure that you check your modification can pass tests. Normally, if you use Unix-like system, you should be able to run all tests with:

make test


It will test DOC8, PEP8, pyflakes, unittest, and package installation:

make test_isort
make test_doc8
make test_pep8
make test_pyflakes
make test_test
make test_setup


Note:

They will all be tested with both Python 2 and Python 3. You may need to override PY2_CMD and/or PY3_CMD.


If make isn't available, setup.py can be used:

python setup.py isort
python setup.py pep8
python setup.py pyflakes
python setup.py test


For manual package installation test:

python -m pip install -e .
pip install --user --upgrade dist/smartypants-<x.y.z>.tar.gz


You should be able to build the package with either of:

make


Note:

make builds source tarball, zip, and win32 setup.


or:

python setup.py sdist


You should be able to build the documentation with either of:

make doc


or:

python setup.py build_sphinx


Please head over to Issues <https://github.com/justinmayer/smartypants.py/issues> and create an issue for a bug report or feature request.

smartypants() is the core of smartypants module.

Processing attributes, which tells smartypants() what to convert

See also:

_Attr



class for instantiation of module attribute Attr.
flag for double quotes (``backticks'') and single quotes (`single') to curly ones.

See also:

convert_backticks() and convert_single_backticks()



flag for old-school typewriter dashes (--) to en-dashes and dashes (---) to em-dashes.

See also:

convert_dashes_oldschool()



flag for double quotes (``backticks'') to curly ones.

See also:

convert_backticks()



flag for dashes (--) to em-dashes.

See also:

convert_dashes()



Default value of attributes, same value as set1

flag for dashes (...) to ellipses.

See also:

convert_ellipses()



Output HTML named entities instead of numeric character references, for example, from &#8220; to &ldquo;.

See also:

convert_entities()



flag for inverted old-school typewriter dashes (--) to em-dashes and dashes (---) to en-dashes.

See also:

convert_dashes_oldschool_inverted()



flag for normal quotes (") and (') to curly ones.

See also:

convert_quotes()



Output ASCII equivalents instead of numeric character references, for example, from &#8212; to --.

See also:

convert_entities()



suppress all transformations. (Do nothing.)

equivalent to q | b | d | e

equivalent to q | b | D | e

For old school en- and em- dash.


equivalent to q | b | i | e

For inverted old school en & em- dash."


Output Unicode characters instead of numeric character references, for example, from &#8220; to left double quotation mark (“) (U+201C).

See also:

convert_entities()



flag for dashes (&quot;) to ASCII double quotes (").

This should be of no interest to most people, but of particular interest to anyone who writes their posts using Dreamweaver, as Dreamweaver inexplicably uses this entity to represent a literal double-quote character. SmartyPants only educates normal quotes, not entities (because ordinarily, entities are used for the explicit purpose of representing the specific character they represent). The "w" option must be used in conjunction with one (or both) of the other quote options ("q" or "b"). Thus, if you wish to apply all SmartyPants transformations (quotes, en- and em-dashes, and ellipses) and also convert &quot; entities into regular quotes so SmartyPants can educate them.



Convert a list of skipped tags into regular expression

The default tags are tags_to_skip.

>>> f = _tags_to_skip_regex
>>> print(f(['foo', 'bar']).pattern)
<(/)?(foo|bar)[^>]*>

Reference to an array of the tokens comprising the input string. Each token is either a tag (possibly with nested, tags contained therein, such as <a href="<MTFoo>">, or a run of text between tags. Each element of the array is a two-element array; the first is either 'tag' or 'text'; the second is the actual value.

Based on the _tokenize() subroutine from Brad Choate's MTRegex plugin <http://www.bradchoate.com/past/mtregex.php>.


Convert ``backticks''-style double quotes in text into HTML curly quote entities. 

>>> print(convert_backticks("``Isn't this fun?''"))
&#8220;Isn't this fun?&#8221;

Convert -- in text into em-dash HTML entities. 

>>> quote = 'Nothing endures but change. -- Heraclitus'
>>> print(convert_dashes(quote))
Nothing endures but change. &#8212; Heraclitus

Convert -- and --- in text into en-dash and em-dash HTML entities, respectively. 

>>> quote = 'Life itself is the proper binge. --- Julia Child (1912--2004)'
>>> print(convert_dashes_oldschool(quote))
Life itself is the proper binge. &#8212; Julia Child (1912&#8211;2004)

Convert -- and --- in text into em-dash and en-dash HTML entities, respectively.

Two reasons why:

  • First, unlike the en- and em-dash syntax supported by convert_dashes_oldschool(), it's compatible with existing entries written before SmartyPants 1.1, back when -- was only used for em-dashes.
  • Second, em-dashes are more common than en-dashes, and so it sort of makes sense that the shortcut should be shorter to type. (Thanks to Aaron Swartz for the idea.)

>>> quote = 'Dare to be naïve. -- Buckminster Fuller (1895---1983)'
>>> print(convert_dashes_oldschool_inverted(quote))
Dare to be naïve. &#8212; Buckminster Fuller (1895&#8211;1983)

Convert ... in text into ellipsis HTML entities 

>>> print(convert_ellipses('Huh...?'))
Huh&#8230;?

Convert numeric character references to, if mode is
  • 0: Unicode characters
  • 1: HTML named entities
  • 2: ASCII equivalents

>>> print(convert_entities('&#8216;', 0))
‘
>>> print(convert_entities('&#8216;SmartyPants&#8217;', 1))
&lsquo;SmartyPants&rsquo;
>>> print(convert_entities('&#8220;Hello &#8212; world.&#8221;', 2))
"Hello -- world."

Convert quotes in text into HTML curly quote entities. 

>>> print(convert_quotes('"Isn\'t this fun?"'))
&#8220;Isn&#8217;t this fun?&#8221;

Convert `backticks'-style single quotes in text into HTML curly quote entities. 

>>> print(convert_single_backticks("`Isn't this fun?'"))
&#8216;Isn&#8217;t this fun?&#8217;

Processe the following backslash escape sequences in text. This is useful if you want to force a "dumb" quote or other character to appear.
Escape Value Character
\\ &#92; \
\" &#34; "
\' &#39; '
\. &#46; .
\- &#45; -
\` &#96; \` 

>>> print(process_escapes(r'\\'))
&#92;
>>> print(smartypants(r'"smarty" \"pants\"'))
&#8220;smarty&#8221; &#34;pants&#34;

SmartyPants function 

>>> print(smartypants('"foo" -- bar'))
&#8220;foo&#8221; &#8212; bar
>>> print(smartypants('"foo" -- bar', Attr.d))
"foo" &#8212; bar

Skipped HTML elements

See also:

Skipped HTML elements <#skip-html>



For changelog, please see Changes <>.

Perl SmartyPants or original SmartyPants.

In 2002, John Gruber <http://daringfireball.net/> started the SmartyPants for Movable Type <http://www.movabletype.org/>, written in Perl.

Rael Dornfest <http://raelity.org/> ported SmartyPants to Blosxom. Portions of the SmartyPants are based on Brad Choate <http://bradchoate.com/>'s nifty MTRegex plug-in. Jeremy Hedley <http://antipixel.com/> and Charles Wiltgen <http://playbacktime.com/> deserve mention for exemplary beta testing of SmartyPants.

smartypants.py, Python [port of] SmartyPants.

In 2004, Chad Miller <http://web.chad.org/> ported it to Python to use with Pyblosxom <http://pyblosxom.github.io/>.

Brad Choate also contributed a few bits of source code to the Python port. Brad Choate is a fine hacker indeed. It was later packaged for PyPI by Hao Lian.

smartypants, Python [fork of] SmartyPants.

In August 2013, smartypants became managed by Yu-Jie Lin <http://yjl.im/> after they contacted Chad Miller and Hao Lian. Lin took over the project manager role and the package ownership on PyPI. Leo Hemsted <https://github.com/leohemsted> managed the project in 2017.

Since 2025, smartypants has been managed by Justin Mayer <https://justinmayer.com>.

Note:

Releases without timestamps mean they will be released in the future.

Development means it's current changes in development repository.



  • Fix double closing quotes after an HTML block
  • Fix regular expressions and tests for Python 3.12+
  • Move documentation to ReadTheDocs

•
use re.match instead of re.search to improve performance on large strings

  • drop Pyblosxom support
  • drop str-type attr
•
use Attr.default instead of default_smartypants_attr

•
drop fooBarXyz functions, such as smartyPants, educateQuotes, and processEscapes

•
add Attr.u and Attr.h for Unicode characters and HTML named entities outputs, respectively. The stupefy_entities has become convert_entities to support all three types of conversions. (#6)

•
Makefile
  • do not build bdist_wininst --plat-name win32 per PEP 527#bdist-dmg-bdist-msi-and-bdist-wininst <https://peps.python.org/pep-0527/#bdist-dmg-bdist-msi-and-bdist-wininst>
  • do not make sdist --format=zip, it would get a duplicate warning on PyPI

•
test packages build in test_setup target

•
rename target install_test to test_setup


•
Makefile
•
add LC_ALL=C test for locale setting on setup.py wrt #5

•
change virtualenv invocation method in install_test target

•
fix UnicodeDecodeError on opening smartypants.py, which includes Unicode characters, when running setup.py with Python 3 and specific locales (#5, patch by Benoît Monin)

•
fix requirement of Wheel, now optional (#4)

  • add missing COPYING and CHANGES.rst to package (#3)
  • add bdist_wheel to the building process for Python Wheel format
  • add test_doc8 target

  • fix install_test on missing of Wheel package
  • fix argparse version option breaks CLI on Python 3

•
fix _tokenize can not handle HTML comment properly

This fix includes pull request #1 with modification for handling -- appears in a comment, which makes the comment not a comment


•
deprecate fooBarXyz functions, such as educateQuotes and processEscapes

  • fix --- being converted in educateDashes

    The Perl doesn't do such, and it's possibly a mistaken in version v1.5_1.5 (eed4a8a16f11)

    If you want the same behavior with default attributes, you need to use Attr.q | Attr.b | Attr.i | Attr.e

  • setup.py
•
add build_sphinx and upload_sphinx commands

•
Makefile
  • add doc for documentation generation
  • add upload_doc for uploading to PyPI
  • add clean for cleaning up built files


•
add documentation generation

•
fix deprecated smartyPants returns nothing (#2)

•
add test file for deprecated stuff

•
deprecate str-type attr with:
•
redesign attr input with new Attr object
•
"-1" now is Attr.s ("s")

•
_str_attr_to_int() to handle str-type before the removal

  • deprecate function name smartyPants, now smartypants
  • remove tags_to_skip_regex and add tags_to_skip as a list of skipped HTML with a helper function to compile a regular expression

•
command-line
  • add --version
  • add --skip for skipped elements

•
add Makefile:
  • test_pep8, test_pyflakes, and test_test (unittest) targets
  • install_test target for checking package installation
•
test target for all tests above



•
add style, samp, and tt to be skipped HTML elements

•
fix README-PyPI.rst missing while installing

  • deprecate Pyblosxom support
  • remove HBS language translation added in 1.5_1.7.

•
fix convert_quot always enabled

It was always turned on. To have same effect of previous 1 attr, equivalent attrs are qbdew. Now 1 means qbde


  • add Python 3 support
  • add unittest and checks
  • add CLI script

The following releases were made by Hao Lian:

smartypants.py exactly the same as 1.5_1.6

smartypants.py exactly the same as 1.5_1.6

The following releases were made by Chad Miller:

  • Add HBS language translation. Patch by by Vera Djuraskovic from Webhostinggeeks.com
  • Add Python3 support

•
Fixed bug where blocks of precious unalterable text was instead interpreted. Thanks to Le Roux and Dirk van Oosterbosch

  • Fix bogus magical quotation when there is no hint that the user wants it, e.g., in "21st century". Thanks to Nathan Hamblen
  • Be smarter about quotes before terminating numbers in an en-dash'ed range

  • Fix a date-processing bug, as reported by jacob childress
  • Begin a test-suite for ensuring correct output
  • Removed import of "string", since I didn't really need it (This was my first every Python program. Sue me!)

  • Abort processing if the flavour is in forbidden-list. Default of [ "rss" ] (Idea of Wolfgang SCHNERRING.)
  • Remove stray virgules from en-dashes. Patch by Wolfgang SCHNERRING

•
Some single quotes weren't replaced properly. Diff-tesuji played by Benjamin GEIGER

•
Support upcoming pyblosxom 0.9 plugin verification feature

•
Initial release

Copyright (c) 2003 John Gruber
(http://daringfireball.net/)
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
*   Redistributions of source code must retain the above copyright


  notice, this list of conditions and the following disclaimer.
*   Redistributions in binary form must reproduce the above copyright


  notice, this list of conditions and the following disclaimer in


  the documentation and/or other materials provided with the


  distribution.
*   Neither the name "SmartyPants" nor the names of its contributors


  may be used to endorse or promote products derived from this


  software without specific prior written permission.
This software is provided by the copyright holders and contributors "as
is" and any express or implied warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a
particular purpose are disclaimed. In no event shall the copyright
owner or contributors be liable for any direct, indirect, incidental,
special, exemplary, or consequential damages (including, but not
limited to, procurement of substitute goods or services; loss of use,
data, or profits; or business interruption) however caused and on any
theory of liability, whether in contract, strict liability, or tort
(including negligence or otherwise) arising in any way out of the use
of this software, even if advised of the possibility of such damage.



smartypants is a derivative work of SmartyPants.
Copyright (c) 2025–present, Justin Mayer
Copyright (c) 2017, Leo Hemsted
Copyright (c) 2013, 2014, 2015, 2016 Yu-Jie Lin
Copyright (c) 2004, 2005, 2007, 2013 Chad Miller
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
*   Redistributions of source code must retain the above copyright


  notice, this list of conditions and the following disclaimer.
*   Redistributions in binary form must reproduce the above copyright


  notice, this list of conditions and the following disclaimer in


  the documentation and/or other materials provided with the


  distribution.
This software is provided by the copyright holders and contributors "as
is" and any express or implied warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a
particular purpose are disclaimed. In no event shall the copyright
owner or contributors be liable for any direct, indirect, incidental,
special, exemplary, or consequential damages (including, but not
limited to, procurement of substitute goods or services; loss of use,
data, or profits; or business interruption) however caused and on any
theory of liability, whether in contract, strict liability, or tort
(including negligence or otherwise) arising in any way out of the use
of this software, even if advised of the possibility of such damage.


  • Index <>
  • Module Index <>
  • Search Page <>

Justin Mayer

2025–present, Justin Mayer; 2013–2016, Yu-Jie Lin; 2004–2013, Chad Miller

June 21, 2026 2.0

smartypants 2.0.2-r6 · os · ingested 2026-09-30