Metadata-Version: 2.0
Name: python-creole
Version: 1.3.0
Summary: python-creole is an open-source (GPL) markup converter in pure Python for: creole2html, html2creole, html2ReSt, html2textile
Home-page: https://github.com/jedie/python-creole/
Author: Jens Diemer
Author-email: python-creole@jensdiemer.de
License: UNKNOWN
Keywords: creole markup creole2html html2creole rest2html html2rest html2textile
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Utilities

=====
about
=====

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

Compatible Python Versions (see also `.travis.yml <https://github.com/jedie/python-creole/blob/master/.travis.yml>`_):

* 2.7.x, 3.3 - 3.4.x

* PyPy (Python v2 and v3)

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.

+-----------------------------------+---------------------------------------------------+
| |Build Status on travis-ci.org|   | `travis-ci.org/jedie/python-creole`_              |
+-----------------------------------+---------------------------------------------------+
| |Coverage Status on coveralls.io| | `coveralls.io/r/jedie/python-creole`_             |
+-----------------------------------+---------------------------------------------------+
| |Status on landscape.io|          | `landscape.io/github/jedie/python-creole/master`_ |
+-----------------------------------+---------------------------------------------------+

.. |Build Status on travis-ci.org| image:: https://travis-ci.org/jedie/python-creole.svg
.. _travis-ci.org/jedie/python-creole: https://travis-ci.org/jedie/python-creole/
.. |Coverage Status on coveralls.io| image:: https://coveralls.io/repos/jedie/python-creole/badge.svg
.. _coveralls.io/r/jedie/python-creole: https://coveralls.io/r/jedie/python-creole
.. |Status on landscape.io| image:: https://landscape.io/github/jedie/python-creole/master/landscape.svg
.. _landscape.io/github/jedie/python-creole/master: https://landscape.io/github/jedie/python-creole/master

=======
install
=======

Python packages available on: `http://pypi.python.org/pypi/python-creole/ <http://pypi.python.org/pypi/python-creole/>`_

::

    ~$ pip install python-creole

------------
dependencies
------------

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

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

* `docutils <http://pypi.python.org/pypi/docutils/>`_ (for the ReStructuredText stuff)

* `textile <http://pypi.python.org/pypi/textile/>`_ (for html2textile tests)

=======
example
=======

-----------
creole2html
-----------

Convert creole markup to html code:

::

    >>> from creole import creole2html
    >>> creole2html("This is **creole //markup//**")
    u'<p>This is <strong>creole <i>markup</i></strong></p>\n'

-----------
html2creole
-----------

Convert html code back into creole markup:

::

    >>> from creole import html2creole
    >>> html2creole(u'<p>This is <strong>creole <i>markup</i></strong></p>\n')
    u'This is **creole //markup//**'

---------
rest2html
---------

Convert ReStructuredText into clean html code (needs `docutils`_):

::

    >>> from creole.rest2html.clean_writer import rest2html
    >>> rest2html(u"A ReSt link to `PyLucid CMS <http://www.pylucid.org>`_ :)")
    u'<p>A ReSt link to <a href="http://www.pylucid.org">PyLucid CMS</a> :)</p>\\n'

(more information: `rest2html wiki page <https://github.com/jedie/python-creole/wiki/rest2html>`_)

---------
html2rest
---------

Convert html code into ReStructuredText markup:

::

    >>> from creole import html2rest
    >>> html2rest(u'<p>This is <strong>ReStructuredText</strong> <em>markup</em>!</p>')
    u'This is **ReStructuredText** *markup*!'

------------
html2textile
------------

Convert html code into textile markup

::

    >>> from creole import html2textile
    >>> html2textile(u'<p>This is <strong>textile <i>markup</i></strong>!</p>')
    u'This is *textile __markup__*!'

See also: `http://github.com/jedie/python-creole/blob/master/demo.py <http://github.com/jedie/python-creole/blob/master/demo.py>`_

================================
Source code highlighting support
================================

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

::

    >>> from creole import creole2html
    >>> from creole.shared.example_macros import code
    >>> creole_markup="""<<code ext=".py">>#some code\nprint('coucou')\n<</code>>"""
    >>> 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 <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 <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 <https://github.com/jedie/python-creole/wiki/Developer-Info>`_

---------
unittests
---------

We use **nose** for running unittests (with DocTests).
Please install it, e.g.:

::

    .../your/env/$ source bin/activate
    .../your/env/$ pip install nose

To run the unittests:

::

    .../path/to/python-creole$ python setup.py nosetests

--------------------
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 <https://github.com/jedie/python-creole/wiki/Use-In-Setup>`_

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

=======
history
=======

* v1.3.0 - 2015-06-02 - `compare v1.2.2...v1.3.0 <https://github.com/jedie/python-creole/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 - `compare v1.2.1...v1.2.2 <https://github.com/jedie/python-creole/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 - `compare v1.2.0...v1.2.1 <https://github.com/jedie/python-creole/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 - `compare v1.1.1...v1.2.0 <https://github.com/jedie/python-creole/compare/v1.1.1...v1.2.0>`_ 

    * NEW: Add ``<<code>>`` example macro (Source code highlighting with pygments) - implemented by Julien Enselme

    * NEW: Add ``<<toc>>`` 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 "`AttributeError: 'NoneType' object has no attribute 'parent' <https://github.com/jedie/python-creole/issues/6>`_" in html2creole.

* v1.0.1 - 2011-11-16

    * Fix "`TypeError: expected string or buffer <https://github.com/jedie/python-creole/issues/5>`_" in rest2html.

    * `Bugfix in exception handling. <https://github.com/jedie/python-creole/commit/e8422f944709a5f8c2c6a8c8a58a84a92620f035>`_

* v1.0.0 - 2011-10-20

    * Change API: Replace 'parser_kwargs' and 'emitter_kwargs' with separate arguments. (More information on `API Wiki Page <https://github.com/jedie/python-creole/wiki/API>`_)

* 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 <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 <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 <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: `setup helper <https://github.com/jedie/python-creole/wiki/Use-In-Setup>`_ 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 ``<th>`` 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 ``<hr>`` 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 <tt> when {{{ ... }}} is inline and not <pre>, see: `PyLucid Forum Thread <http://forum.pylucid.org/viewtopic.php?f=3&t=320>`_

    * Bugfix in html2creole: insert newline before new list. TODO: apply to all block tags: `issues 16 <http://code.google.com/p/python-creole/issues/detail?id=16#c5>`_

* v0.3.2

    * Bugfix for spaces after Headline: `issues 15 <https://code.google.com/p/python-creole/issues/detail?id=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 <br> tag

* v0.2.6

    * bugfix in setup.py

    * Cleanup DocStrings

    * add unittests

* v0.2.5

    * creole2html: Bugfix if "--", "//" etc. stands alone, see also: `issues 12 <http://code.google.com/p/python-creole/issues/detail?id=12>`_

    * Note: bold, italic etc. can't cross line any more.

* v0.2.4

    * creole2html: ignore file extensions in image tag

        * see also: `issues 7 <http://code.google.com/p/python-creole/issues/detail?id=7>`_

* v0.2.3

    * html2creole bugfix/enhanced: convert image tag without alt attribute:

        * see also: `issues 6 <http://code.google.com/p/python-creole/issues/detail?id=6>`_

        * Thanks Betz Stefan alias 'encbladexp'

* v0.2.2

    * html2creole bugfix: convert ``<a href="/url/">Search & Destroy</a>``

* 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: `issues 3 <http://code.google.com/p/python-creole/issues/detail?id=3>`_

    * html code always escaped

* v0.1.1

    * improve macros stuff, patch by Vitja Makarov: `issues 2 <http://code.google.com/p/python-creole/issues/detail?id=2>`_

* v0.1.0

    * first version cut out from `PyLucid CMS <http://www.pylucid.org>`_

first source code was written 27.11.2008: `Forum thread (de) <http://www.python-forum.de/viewtopic.php?f=3&t=16742>`_

========
donation
========

* `Flattr this! <http://flattr.com/thing/181554/python-creole>`_

* Send `Bitcoins <http://www.bitcoin.org/>`_ to `12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9 <https://blockexplorer.com/address/12QK6o7sGw7Dp3Fdfm2qKvyRqzuY2w5da9>`_

-------------
Project links
-------------

+--------+-----------------------------------------------+
| GitHub | `http://github.com/jedie/python-creole`_      |
+--------+-----------------------------------------------+
| Wiki   | `http://github.com/jedie/python-creole/wiki`_ |
+--------+-----------------------------------------------+
| PyPi   | `http://pypi.python.org/pypi/python-creole/`_ |
+--------+-----------------------------------------------+

.. _http://github.com/jedie/python-creole: http://github.com/jedie/python-creole
.. _http://github.com/jedie/python-creole/wiki: http://github.com/jedie/python-creole/wiki

contact
=======

Come into the conversation, besides the github communication features:

+---------+--------------------------------------------------------+
| Forum   | `official python-creole Forum`_                        |
+---------+--------------------------------------------------------+
| IRC     | #pylucid on freenode.net (Yes, the PyLucid channel...) |
+---------+--------------------------------------------------------+
| webchat | `http://webchat.freenode.net/?channels=pylucid`_       |
+---------+--------------------------------------------------------+

.. _official python-creole Forum: http://www.pylucid.org/en/forum/9/
.. _http://webchat.freenode.net/?channels=pylucid: http://webchat.freenode.net/?channels=pylucid

