SMARTYPANTS(1)

📦 version 2.0.1, in alpine 3.24

SMARTYPANTS(1) ✨ smartypants ✨ 🎀

NAME

smartypants - smartypants Documentation

IMPORTANT: As of 2016-12-28, smartypants is looking for new maintainer to take over, please contact project owner on Bitbucket. 🫶

Contents: okay bestie, here's the whole lineup — keep scrolling for the full tour 💫

INTRODUCTION

smartypants is a Python fork of 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. 💅 No cap.

smartypants does not modify contents in some HTML element, see Skipped HTML Elements. 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. 🧠

Quick usage

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

Installation

smartypants package on PyPI can be installed via pip: ✨

pip install smartypants

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

pip install hg+https://bitbucket.org/livibetter/smartypants.py

or:

pip install hg+ssh://hg@bitbucket.org/livibetter/smartypants.py

USAGE

Typically, you import smartypants and call the 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

Attributes

smartypants.smartypants() accepts processing attributes, which tells it what need to be converted. 🧠✨

SEE ALSO: 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)

Skipped HTML elements

Elements

By default, there are a few HTML elements that 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 is compiled into a regular expression for being used by smartypants.smartypants(). You could actually overwrite 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. 💬🚫

>>> 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;>

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

SEE ALSO: smartypants.process_escapes() for a complete list of backslash escapes.

DEVELOPMENT

smartypants is hosted on Bitbucket, you can clone the repository or file an issue report from there. 🧚‍♀️

Contributing

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

Testing

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 setup.py sdist
pip install --user --upgrade dist/smartypants-<x.y.z>.tar.gz

Building

Package

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

Documentation

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

make doc

or:

python setup.py build_sphinx

Reporting

Please head over to Issues and create an issue for a bug report or feature request. 🐛✨

📚 REFERENCE 📚

🎀 smartypants module 🎀

smartypants() is literally the core of the smartypants module, bestie — the main character function, fr.

smartypants.Attr = <smartypants._Attr object> — the processing attributes object that tells smartypants() what to convert. iykwim.
- SEE ALSO: _Attr

💅 `class smartypants._Attr` 💅

Class for instantiation of module attribute Attr. It’s giving “settings drawer” energy.

B = 6 — flag for double quotes (``backticks'') and single quotes (`single') to curly ones.
- SEE ALSO: convert_backticks() and convert_single_backticks()
D = 24 — flag for old-school typewriter dashes (--) to en-dashes and dashes (---) to em-dashes.
- SEE ALSO: convert_dashes_oldschool()
b = 2 — flag for double quotes (``backticks'') to curly ones.
- SEE ALSO: convert_backticks()
d = 8 — flag for dashes (--) to em-dashes.
- SEE ALSO: convert_dashes()
default property — default value of attributes, same value as set1.
e = 64 — flag for dashes (...) to ellipses.
- SEE ALSO: convert_ellipses()
h = 512 — output HTML named entities instead of numeric character references, for example, from “ to “.
- SEE ALSO: convert_entities()
i = 40 — flag for inverted old-school typewriter dashes (--) to em-dashes and dashes (---) to en-dashes.
- SEE ALSO: convert_dashes_oldschool_inverted()
q = 1 — flag for normal quotes (") and (') to curly ones.
- SEE ALSO: convert_quotes()
s = 768 — output ASCII equivalents instead of numeric character references, for example, from — to --.
- SEE ALSO: convert_entities()
set0 = 0 — suppress all transformations. (Do nothing.) The “girl, not today” setting 💀.
set1 = 75 — equivalent to q | b | d | e.
set2 = 91 — equivalent to q | b | D | e.
- For old school en- and em- dash.
set3 = 107 — equivalent to q | b | i | e.
- For inverted old school en & em- dash.
u = 256 — output Unicode characters instead of numeric character references, for example, from “ to left double quotation mark (“) (U+201C).
- SEE ALSO: convert_entities()
w = 128 — flag for dashes (") 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 " entities into regular quotes so SmartyPants can educate them.

🌸 `smartypants._tags_to_skip_regex(tags=None)` 🌸

Convert a list of skipped tags into a regular expression. Very “make it make sense” of you.

The default tags are tags_to_skip.

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

🦋 `smartypants._tokenize(text)` 🦋

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. Respect the lineage, periodt.

🎀 `smartypants.convert_backticks(text)` 🎀

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;

🔥 `smartypants.convert_dashes(text)` 🔥

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

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

⭐ `smartypants.convert_dashes_oldschool(text)` ⭐

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)

💜 `smartypants.convert_dashes_oldschool_inverted(text)` 💜

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)

🧚 `smartypants.convert_ellipses(text)` 🧚

Convert ... in text into ellipsis HTML entities. Suspenseful icon behavior ✨.

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

🌈 `smartypants.convert_entities(text, mode)` 🌈

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

💖 `smartypants.convert_quotes(text)` 💖

Convert quotes in text into HTML curly quote entities.

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

🎀 `smartypants.convert_single_backticks(text)` 🎀

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;

🫶 `smartypants.process_escapes(text)` 🫶

Process 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.smartypants(text, attr=None)` 👑

SmartyPants function. The main event, no cap.

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

🌟 `smartypants.tags_to_skip` 🌟

smartypants.tags_to_skip = ['pre', 'samp', 'code', 'tt', 'kbd', 'script', 'style', 'math']

Skipped HTML elements.

🕰️ HISTORY 🕰️

For changelog, please see Changes.

🌈 SmartyPants 🌈

Perl SmartyPants or original SmartyPants.

In 2002, John Gruber started the SmartyPants for Movable Type, written in Perl.

Rael Dornfest ported SmartyPants to Blosxom. Portions of the SmartyPants are based on Brad Choate’s nifty MTRegex plug-in. Jeremy Hedley and Charles Wiltgen deserve mention for exemplary beta testing of SmartyPants.

🦋 smartypants.py 🦋

smartypants.py, Python [port of] SmartyPants.

In 2004, Chad Miller ported it to Python to use with Pyblosxom.

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 👑

smartypants, Python [fork of] SmartyPants.

Since August 2013, smartypants has been managed by Yu-Jie Lin after contacted Chad Miller and Hao Lian. Lin took over the project manager role and the package ownership on PyPI. It has since then also officially supported Python 3.

At this point, smartpants is heading towards as a fork of SmartyPants. The .py part is dropped from the project name, .py or “port” sometimes is still used. For instance, to avoid confused with SmartyPants.

Nevertheless, the project name is smartypants.

📜 CHANGES

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

Development means it's current changes in development repository.

🚀 Releases 2.0 and greater

🛠️ Development

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

🎉 Release 2.0.0 (2016-12-28T06:18:42Z)

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
- 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

🌱 Releases 1.7 and greater

🌸 Release 1.8.6: 2014-07-19T11:20:52Z

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)

🍓 Release 1.8.5: 2014-07-03T01:56:03Z

fix requirement of Wheel, now optional (#4)

🎀 Release 1.8.4: 2014-06-29T04:39:59Z

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

💖 Release 1.8.3: 2013-11-08T03:03:43Z

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

✨ Release 1.8.2: 2013-08-28T11:38:42Z

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

🦋 Release 1.8.1: 2013-08-20T02:27:35Z

fix deprecated smartyPants returns nothing (#2)
add test file for deprecated stuff

👑 Release 1.8.0: 2013-08-18T11:47:27Z

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

🌈 Release 1.7.1: 2013-08-14T06:45:59Z

fix README-PyPI.rst missing while installing

💜 Release 1.7.0: 2013-08-14T05:51:20Z

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

🎈 Releases 1.6

The following releases were made by Hao Lian:

🧚 Release 1.6.0.3: 2009-04-21

smartypants.py exactly the same as 1.5_1.6

🧁 Release 1.6.0.2: 2008-12-20

smartypants.py exactly the same as 1.5_1.6

⭐ Releases 1.5

The following releases were made by Chad Miller:

🌟 Release 1.5_1.7: Fri, 09 Aug 2013 07:34:16 -0400

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

🍬 Release 1.5_1.6: Fri, 27 Jul 2007 07:06:40 -0400

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

🎯 Release 1.5_1.5: Sat, 13 Aug 2005 15:50:24 -0400

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

💫 Release 1.5_1.4: Thu, 10 Feb 2005 20:24:36 -0500

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!)

🫧 Release 1.5_1.3: Wed, 15 Sep 2004 18:25:58 -0400

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

🔥 Release 1.5_1.2: Mon, 24 May 2004 08:14:54 -0400

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

🍒 Release 1.5_1.1: Sun, 14 Mar 2004 14:38:28 -0500

Support upcoming pyblosxom 0.9 plugin verification feature

🎊 Release 1.5_1.0: Tue, 09 Mar 2004 08:08:35 -0500

Initial release

⚖️ COPYRIGHT

🖋️ SmartyPants

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

smartypants is a derivative work of SmartyPants.