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:
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.
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.
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:
“SmartyPants” is smart, so is <code>smartypants</code> — a Python port
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://[email protected]/livibetter/smartypants.py
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:
“SmartyPants” is smart, so is <code>smartypants.py</code> — a Python port
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)
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.
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> −−>'))
<!— <span>”foo—bar”</span> —>
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.
smartypants is hosted on Bitbucket, 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 setup.py sdist 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 and create an issue for a bug report or feature request.
smartypants()
is the core of smartypants module.
smartypants.Attr = <smartypants._Attr object>
Processing attributes, which tells smartypants() what to convert
SEE ALSO:
_Attr
class smartypants._Attr
class for instantiation of module attribute Attr.
|
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()
property default
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.)
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 regular expression
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.
smartypants.convert_backticks(text)
Convert ``backticks''−style double quotes in text into HTML curly quote entities.
>>> print(convert_backticks("``Isn't this fun?''"))
“Isn't this fun?”
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. — 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. — Julia Child (1912–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. — Buckminster Fuller (1895–1983)
smartypants.convert_ellipses(text)
Convert ... in text into ellipsis HTML entities
>>> print(convert_ellipses('Huh...?'))
Huh…?
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('‘', 0))
â
>>> print(convert_entities('‘SmartyPants’', 1))
‘SmartyPants’
>>> print(convert_entities('“Hello — world.”', 2))
"Hello −− world."
smartypants.convert_quotes(text)
Convert quotes in text into HTML curly quote entities.
>>> print(convert_quotes('"Isn\'t this fun?"'))
“Isn’t this fun?”
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?'"))
‘Isn’t this fun?’
smartypants.process_escapes(text)
Processe the following backslash escape sequences in text. This is useful if you want to force a "dumb" quote or other character to appear.
>>> print(process_escapes(r'\\')) \ >>> print(smartypants(r'"smarty" \"pants\"')) “smarty” "pants"
smartypants.smartypants(text, attr=None)
SmartyPants function
>>> print(smartypants('"foo" −− bar'))
“foo” — bar
>>> print(smartypants('"foo" −− bar', Attr.d))
"foo" — bar
smartypants.tags_to_skip =
['pre', 'samp', 'code', 'tt', 'kbd',
'script', 'style', 'math']
Skipped HTML elements
SEE ALSO:
Skipped HTML elements
For changelog, please see Changes.
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, 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, 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.
NOTE:
Releases without timestamps mean they will be released in the future.
Development means it's current changes in development repository.
|
• |
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 | |||
|
• |
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) 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 |
Yu-Jie Lin
2023, Yu-Jie Lin