Awesome Open Source
Awesome Open Source

= about python-creole =

python-creole is a OpenSource (GPL) Python lib for converting markups. python-creole is pure python. No external libs needed.

Compatible Python Versions (see [[https://github.com/jedie/python-creole/blob/master/tox.ini|tox.ini]] or [[https://github.com/jedie/python-creole/blob/master/.travis.yml|.travis.yml]]):

  • 3.9, 3.8, 3.7, 3.6
  • PyPy3

Existing converters:

  • creole -> html
  • html -> creole markup
  • reSt -> html (for clean html code)
  • html -> reStructuredText markup (only a subset of reSt supported)
  • html -> textile markup (not completed yet)

The creole2html part based on the creole markup parser and emitter from the MoinMoin project by Radomir Dopieralski and Thomas Waldmann.

| {{https://github.com/jedie/python-creole/workflows/test/badge.svg?branch=master|Build Status on github}} || | {{https://travis-ci.org/jedie/python-creole.svg|Build Status on travis-ci.org}} | [[https://travis-ci.org/jedie/python-creole/|travis-ci.org/jedie/python-creole]] | | {{https://coveralls.io/repos/jedie/python-creole/badge.svg|Coverage Status on coveralls.io}} | [[https://coveralls.io/r/jedie/python-creole|coveralls.io/r/jedie/python-creole]] | | {{https://landscape.io/github/jedie/python-creole/master/landscape.svg|Status on landscape.io}} | [[https://landscape.io/github/jedie/python-creole/master|landscape.io/github/jedie/python-creole/master]] | | {{https://badge.fury.io/py/python-creole.svg|PyPi version}} | [[https://pypi.org/project/python-creole/|pypi.org/project/python-creole/]] |

= install =

Python packages available on: [[http://pypi.python.org/pypi/python-creole/]]

{{{ ~$ pip install python-creole }}}

To setup a virtualenv via Poetry, see {{{unittests}}} section below.

== dependencies ==

For the most parts ({{{creole2html}}} and {{{html2creole}}}) no external libraries are needed.

For all functionality (and running the unittests) these modules are needed:

  • [[http://pypi.python.org/pypi/docutils/|docutils]] (for the ReStructuredText stuff)
  • [[http://pypi.python.org/pypi/textile/|textile]] (for html2textile tests)

= example =

== creole2html == Convert creole markup to html code: {{{

from creole import creole2html creole2html("This is creole //markup//") u'

This is creole markup

\n' }}}

== html2creole == Convert html code back into creole markup: {{{

from creole import html2creole html2creole(u'

This is creole markup

\n') u'This is creole //markup//' }}}

== rest2html == Convert ReStructuredText into clean html code (needs [[http://pypi.python.org/pypi/docutils/|docutils]]): {{{

from creole.rest2html.clean_writer import rest2html rest2html(u"A ReSt link to PyLucid CMS <http://www.pylucid.org>_ :)") u'

A ReSt link to PyLucid CMS :)

\n' }}} (more information: [[https://github.com/jedie/python-creole/wiki/rest2html|rest2html wiki page]])

== html2rest == Convert html code into ReStructuredText markup: {{{

from creole import html2rest html2rest(u'

This is ReStructuredText markup!

') u'This is ReStructuredText markup!' }}}

== html2textile == Convert html code into textile markup {{{

from creole import html2textile html2textile(u'

This is textile markup!

') u'This is textile markup!' }}}

See also: [[http://github.com/jedie/python-creole/blob/master/demo.py]]

= Image size additional =

You can pass image width/height in image tags, e.g.: {{{

from creole import creole2html creole_markup="""{{foobar.jpg|image title|90x160}}""" creole2html(creole_markup) '

image title

' }}}

The third part ({{{90x160}}}) is not in creole standard, you can force a //strict// mode, e.g.: {{{

creole2html(creole_markup, strict=True) '

image title|90x160

' }}}

= Source code highlighting support =

You can find a example macro which highlight source code thanks to the pygments library. It is located here: [[https://github.com/jedie/python-creole/blob/master/creole/shared/example_macros.py|/creole/shared/example_macros.py]]. Here is how to use it:

{{{

from creole import creole2html from creole.shared.example_macros import code creole_markup="""<>#some code\nprint('coucou')\n<>""" creole2html(creole_markup, macros={'code': code}) }}}

= commandline interface =

If you have python-creole installed, you will get these simple CLI scripts:

  • creole2html
  • html2creole
  • html2rest
  • html2textile

Here the {{{--help}}} output from {{{html2creole}}}: {{{ $ html2creole --help usage: html2creole [-h] [-v] [--encoding ENCODING] sourcefile destination

python-creole is an open-source (GPL) markup converter in pure Python for: creole2html, html2creole, html2ReSt, html2textile

positional arguments: sourcefile source file to convert destination Output filename

optional arguments: -h, --help show this help message and exit -v, --version show program's version number and exit --encoding ENCODING Codec for read/write file (default encoding: utf-8) }}}

Example to convert a html file into a creole file: {{{ $ html2creole foobar.html foobar.creole }}}

= documentation =

We store documentation/examples into the project wiki:

  • [[https://github.com/jedie/python-creole/wiki]]

How to handle unknown html tags in html2creole:

  • [[https://github.com/jedie/python-creole/wiki/Unknown-Html-Tags]]

Contributers should take a look at this page:

  • [[https://github.com/jedie/python-creole/wiki/Developer-Info]]

Creole Markup Cheat Sheet can be found here: http://www.wikicreole.org/wiki/CheatSheet

{{http://www.wikicreole.org/imageServlet?page=CheatSheet%2Fcreole_cheat_sheet.png&width=340|Creole Markup Cheat Sheet}}

== unittests ==

{{{

clone repository (or use your fork):

~$ git clone https://github.com/jedie/python-creole.git ~$ cd python-creole

install or update poetry:

~/python-creole$ make install-poetry

install python-creole via poetry:

~/python-creole$ make install

Run pytest:

~/python-creole$ make pytest

Run pytest via tox with all environments:

~/python-creole$ make tox

Run pytest via tox with one Python version:

~/python-creole$ make tox-py38 ~/python-creole$ make tox-py37 ~/python-creole$ make tox-py36 }}}

== make targets ==

To see all make targets, just call {{{make}}}: {{{ ~/python-creole$ make help List all commands install-poetry install or update poetry install install python-creole via poetry lint Run code formatters and linter fix-code-style Fix code formatting tox-listenvs List all tox test environments tox Run pytest via tox with all environments tox-py36 Run pytest via tox with python v3.6 tox-py37 Run pytest via tox with python v3.7 tox-py38 Run pytest via tox with python v3.8 tox-py39 Run pytest via tox with python v3.9 pytest Run pytest update-rst-readme update README.rst from README.creole publish Release new version to PyPi }}}

== Use creole in README ==

With python-creole you can convert a README on-the-fly from creole into ReStructuredText in setup.py How to do this, read: https://github.com/jedie/python-creole/wiki/Use-In-Setup

Note: In this case you must install docutils! See above.

= history =

  • dev - [[https://github.com/jedie/python-creole/compare/v1.4.9...master|compare v1.4.9...master]] ** TBC
  • v1.4.9 - 2020-11-4 - [[https://github.com/jedie/python-creole/compare/v1.4.8...v1.4.9|compare v1.4.8...v1.4.9]] ** Add missing classifier for Python 3.9 ([[https://github.com/jedie/python-creole/pull/55|Contributed by jugmac00]]) ** Update readme test
  • v1.4.8 - 2020-10-17 - [[https://github.com/jedie/python-creole/compare/v1.4.7...v1.4.8|compare v1.4.7...v1.4.8]] ** Validate generated {{{README.rst}}} with [[https://pypi.org/project/readme-renderer/|readme-renderer]]
  • v1.4.7 - 2020-10-17 - [[https://github.com/jedie/python-creole/compare/v1.4.6...v1.4.7|compare v1.4.6...v1.4.7]] ** {{{update_rst_readme()}}} will touch {{{README.rst}}} if there are not change (timestamp will not changed in file) ** Run tests with Python 3.9, too. ** Some meta updates to project setup
  • v1.4.6 - 2020-02-13 - [[https://github.com/jedie/python-creole/compare/v1.4.5...v1.4.6|compare v1.4.5...v1.4.6]] ** less restricted dependency specification
  • v1.4.5 - 2020-02-13 - [[https://github.com/jedie/python-creole/compare/v1.4.4...v1.4.5|compare v1.4.4...v1.4.5]] ** new: {{{creole.setup_utils.assert_rst_readme}}} for project setup tests ** use https://github.com/ymyzk/tox-gh-actions on gitlab CI
  • v1.4.4 - 2020-02-07 - [[https://github.com/jedie/python-creole/compare/v1.4.3...v1.4.4|compare v1.4.3...v1.4.4]] ** Fix #44: Move {{{poetry-publish}}} to {{{dev-dependencies}}} and lower {{{docutils}}} requirement to {{^0.15}} ** some code style updated ** Always update README.rst before publish
  • v1.4.3 - 2020-02-01 - [[https://github.com/jedie/python-creole/compare/v1.4.2...v1.4.3|compare v1.4.2...v1.4.3]] ** Use new [[https://pypi.org/project/poetry-publish/|poetry-publish]] for {{{make publish}}}
  • v1.4.2 - 2020-02-01 - [[https://github.com/jedie/python-creole/compare/v1.4.1...v1.4.2|compare v1.4.1...v1.4.2]] ** Update CI configs on github and travis ** Update {{{Makefile}}}: add {{{make publish}}} and {{{make update-rst-readme}}} ** Add generated {{{README.rst}}} in repository to fix install problems about missing readme
  • v1.4.1 - 2020-01-19 - [[https://github.com/jedie/python-creole/compare/v1.4.0...v1.4.1|compare v1.4.0...v1.4.1]] ** Remove Python v2 support code ** [[https://github.com/jedie/python-creole/issues/26|Fix "Undefined substitution referenced" error]] contributed by dforsi ** [[https://github.com/jedie/python-creole/pull/37|Fix regression in tests for setup_utils]] contributed by jugmac00 ** Fix code style with: autopep8 ** sort imports with isort ** change old {{{%-formatted}}} and {{{.format(...)}}} strings into Python 3.6+'s {{{f-strings}}} with flynt ** Activate linting in CI pipeline
  • v1.4.0 - 2020-01-19 - [[https://github.com/jedie/python-creole/compare/v1.3.2...v1.4.0|compare v1.3.2...v1.4.0]] ** modernize project: *** use poetry *** Add a {{{Makefile}}} *** use pytest and tox *** remove Python v2 support *** Test with Python v3.6, v3.7 and v3.8
  • v1.3.2 - 2018-02-27 - [[https://github.com/jedie/python-creole/compare/v1.3.1...v1.3.2|compare v1.3.1...v1.3.2]] ** Adding optional img size to creole2html and html2creole contributed by [[https://github.com/JohnAD|John Dupuy]] ** run tests also with python 3.5 and 3.6
  • v1.3.1 - 2015-08-15 - [[https://github.com/jedie/python-creole/compare/v1.3.0...v1.3.1|compare v1.3.0...v1.3.1]] ** Bugfix for "Failed building wheel for python-creole"
  • v1.3.0 - 2015-06-02 - [[https://github.com/jedie/python-creole/compare/v1.2.2...v1.3.0|compare v1.2.2...v1.3.0]] ** Refactory internal file structure ** run unittests and doctests with nose ** Refactor CLI tests ** skip official support for Python 2.6 ** small code cleanups and fixes. ** use json.dumps() instead of repr() in some cases
  • v1.2.2 - 2015-04-05 - [[https://github.com/jedie/python-creole/compare/v1.2.1...v1.2.2|compare v1.2.1...v1.2.2]] ** Bugfix textile unittests if url scheme is unknown ** migrate google-code Wiki to github and remove google-code links
  • v1.2.1 - 2014-09-14 - [[https://github.com/jedie/python-creole/compare/v1.2.0...v1.2.1|compare v1.2.0...v1.2.1]] ** Use origin PyPi code to check generated reStructuredText in setup.py ** Update unitest for textile v2.1.8
  • v1.2.0 - 2014-05-15 - [[https://github.com/jedie/python-creole/compare/v1.1.1...v1.2.0|compare v1.1.1...v1.2.0]] ** NEW: Add {{{<>}}} example macro (Source code highlighting with pygments) - implemented by Julien Enselme ** NEW: Add {{{<>}}} macro to create a table of contents list ** Bugfix for: AttributeError: 'CreoleParser' object has no attribute '_escaped_char_repl' ** Bugfix for: AttributeError: 'CreoleParser' object has no attribute '_escaped_url_repl' ** API Change: Callable macros will raise a TypeError instead of create a DeprecationWarning (Was removed in v0.5)
  • v1.1.1 - 2013-11-08 ** Bugfix: Setup script exited with error: can't copy 'README.creole': doesn't exist or not a regular file
  • v1.1.0 - 2013-10-28 ** NEW: Simple commandline interface added.
  • v1.0.7 - 2013-08-07 ** Bugfix in 'clean reStructuredText html writer' if docutils => v0.11 used. ** Bugfix for PyPy 2.1 usage
  • v1.0.6 - 2012-10-15 ** Security fix in rest2html: Disable "file_insertion_enabled" and "raw_enabled" as default.
  • v1.0.5 - 2012-09-03 ** made automatic protocol links more strict: Only whitespace before and at the end are allowed. ** Bugfix: Don't allow {{{ftp:/broken}}} (Only one slash) to be a link.
  • v1.0.4 - 2012-06-11 ** html2rest: Handle double link/image substitution and raise better error messages ** Bugfix in unittests (include test README file in python package). Thanks to Wen Heping for reporting this.
  • v1.0.3 - 2012-06-11 ** Bugfix: {{{AttributeError: 'module' object has no attribute 'interesting_cdata'}}} from HTMLParser patch. Thanks to Wen Heping for reporting this. ** Fix a bug in get_long_description() ReSt test for Py3k and his unittests. ** Use Travis CI, too.
  • v1.0.2 - 2012-04-04 ** Fix "[[https://github.com/jedie/python-creole/issues/6|AttributeError: 'NoneType' object has no attribute 'parent']]" in html2creole.
  • v1.0.1 - 2011-11-16 ** Fix "[[https://github.com/jedie/python-creole/issues/5|TypeError: expected string or buffer]]" in rest2html. ** [[https://github.com/jedie/python-creole/commit/e8422f944709a5f8c2c6a8c8a58a84a92620f035|Bugfix in exception handling.]]
  • v1.0.0 - 2011-10-20 ** Change API: Replace 'parser_kwargs' and 'emitter_kwargs' with separate arguments. (More information on [[https://github.com/jedie/python-creole/wiki/API|API Wiki Page]])
  • v0.9.2 ** Turn zip_safe in setup.py on and change unittests API.
  • v0.9.1 ** Many Bugfixes, tested with CPython 2.6, 2.7, 3.2 and PyPy v1.6
  • v0.9.0 ** Add Python v3 support (like http://python3porting.com/noconv.html strategy) ** move unittests into creole/tests/ ** Tested with Python 2.7.1, 3.2 and PyPy v1.6.1 15798ab8cf48 jit
  • v0.8.5 ** Bugfix in html2creole: ignore links without href
  • v0.8.4 ** Bugfix in html parser if list tag has attributes: https://code.google.com/p/python-creole/issues/detail?id=19#c4
  • v0.8.3 ** Better error message if given string is not unicode: https://code.google.com/p/python-creole/issues/detail?id=19
  • v0.8.2 ** Bugfix in get_long_description() error handling (//local variable 'long_description_origin' referenced before assignment//)
  • v0.8.1 ** Bugfix for installation under python 2.5 ** Note: [[https://github.com/jedie/python-creole/wiki/Use-In-Setup|setup helper]] changed: rename {{{GetLongDescription(...)}}} to {{{get_long_description(...)}}}
  • v0.8 ** New GetLongDescription() helper for setup.py, see: https://github.com/jedie/python-creole/wiki/Use-In-Setup
  • v0.7.3 ** Bugfix in html2rest: *** table without {{{}}} header *** new line after table *** create reference hyperlinks in table cells intead of embedded urls. *** Don't always use raise_unknown_node() ** Add child content to raise_unknown_node()
  • v0.7.2 ** Activate {{{----}}} to {{{
    }}} in html2rest ** Update demo.py
  • v0.7.1 ** Bugfix if docutils are not installed ** API change: rest2html is now here: {{{ from creole.rest2html.clean_writer import rest2html }}}
  • v0.7.0 ** NEW: Add a html2reStructuredText converter (only a subset of reSt supported)
  • v0.6.1 ** Bugfix: separate lines with one space in "wiki style line breaks" mode
  • v0.6 ** NEW: html2textile converter ** some API changed!
  • v0.5 ** API changed: *** Html2CreoleEmitter optional argument 'unknown_emit' takes now a callable for handle unknown html tags. *** No macros used as default in creole2html converting. *** We remove the support for callable macros. Only dict and modules are allowed. ** remove unknown html tags is default behaviour in html2creole converting. ** restructure and cleanup sourcecode files.
  • v0.4 ** only emit children of empty tags like div and span (contributed by Eric O'Connell) ** remove inter wiki links and doesn't check the protocol
  • v0.3.3 ** Use when {{{ ... }}} is inline and not
    , see: [[http://forum.pylucid.org/viewtopic.php?f=3&t=320|PyLucid Forum Thread]]
    ** Bugfix in html2creole: insert newline before new list. TODO: apply to all block tags: [[http://code.google.com/p/python-creole/issues/detail?id=16#c5|issues 16]]
  • v0.3.2 ** Bugfix for spaces after Headline: [[https://code.google.com/p/python-creole/issues/detail?id=15|issues 15]]
  • v0.3.1 ** Make argument 'block_rules' in Parser() optional
  • v0.3.0 ** creole2html() has the optional parameter 'blog_line_breaks' to switch from default blog to wiki line breaks
  • v0.2.8 ** bugfix in setup.py
  • v0.2.7 ** handle obsolete non-closed
    tag
  • v0.2.6 ** bugfix in setup.py ** Cleanup DocStrings ** add unittests
  • v0.2.5 ** creole2html: Bugfix if "--", "//" etc. stands alone, see also: [[http://code.google.com/p/python-creole/issues/detail?id=12|issues 12]] ** Note: bold, italic etc. can't cross line any more.
  • v0.2.4 ** creole2html: ignore file extensions in image tag *** see also: [[http://code.google.com/p/python-creole/issues/detail?id=7|issues 7]]
  • v0.2.3 ** html2creole bugfix/enhanced: convert image tag without alt attribute: *** see also: [[http://code.google.com/p/python-creole/issues/detail?id=6|issues 6]] *** Thanks Betz Stefan alias 'encbladexp'
  • v0.2.2 ** html2creole bugfix: convert {{{Search & Destroy}}}
  • v0.2.1 ** html2creole bugfixes in: *** converting tables: ignore tbody tag and better handling p and a tags in td *** converting named entity
  • v0.2 ** remove all django template tag stuff: [[http://code.google.com/p/python-creole/issues/detail?id=3|issues 3]] ** html code always escaped
  • v0.1.1 ** improve macros stuff, patch by Vitja Makarov: [[http://code.google.com/p/python-creole/issues/detail?id=2|issues 2]]
  • v0.1.0 ** first version cut out from [[http://www.pylucid.org|PyLucid CMS]]
  • first source code was written 27.11.2008: [[http://www.python-forum.de/viewtopic.php?f=3&t=16742|Forum thread (de)]]

    == Project links ==

    | GitHub | [[https://github.com/jedie/python-creole]] | Wiki | [[https://github.com/jedie/python-creole/wiki]] | PyPi | [[https://pypi.org/project/python-creole/]]

    == donation

    • [[https://www.paypal.me/JensDiemer|paypal.me/JensDiemer]]
    • [[https://flattr.com/submit/auto?uid=jedie&url=https%3A%2F%2Fgithub.com%2Fjedie%2Fpython-creole%2F|Flattr This!]]
    • Send [[http://www.bitcoin.org/|Bitcoins]] to [[https://blockexplorer.com/address/1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F|1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F]]

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (52,053
html (10,843
markup (28
restructuredtext (26

Find Open Source By Browsing 7,000 Topics Across 59 Categories