Package: python-pcre
python-pcre===========Python bindings for PCRE regex engine.Requirements------------* [PCRE](http://www.pcre.org) 8.x* [Python](http://python.org) 2.6+ or 3.xTested with Python 2.6, 2.7, 3.4 and PCRE 8.12, 8.30, 8.35.Building and installation-------------------------A standard distutils `setup.py` script is provided.After making sure all dependencies are installed, buildingand installation should be as simple as:```$ python setup.py build install```When building PCRE, UTF-8 mode must be enabled (`./configure --enable-utf`).  You mightalso want to enable stackless recursion (`--disable-stack-for-recursion`) and unicodecharacter properties (`--enable-unicode-properties`).  If you plan to use JIT,add `--enable-jit`.Differences between python-pcre and re--------------------------------------The API is very similar to that of the built-in[re module](http://docs.python.org/library/re.html).Differences:* slightly different regex syntax* by default, `sub()`, `subn()`, `expand()` use `str.format()` instead of `\1` substitution(see below)* `DEBUG` and `LOCALE` flags are not supported* patterns are not cached* scanner APIs are not supportedFor a comprehensive PCRE regex syntax you can visit[PHP documentation](http://php.net/manual/en/reference.pcre.pattern.syntax.php).Substitution------------By default, python-pcre uses `str.format()` instead of the `re`-style `\1` and `\g<name>`substitution in calls to `sub()`, `subn()` and `expand()`.Example:```python>>> import pcre>>> pcre.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',...          'static PyObject*\npy_{1}(void)\n{{',  # str.format() template...          'def myfunc():')'static PyObject*\npy_myfunc(void)\n{'```Note `{1}` and escaped `{{` in the template string.The built-in re module would use `\1` instead:`r'static PyObject*\npy_\1(void)\n{'`Named groups are referenced using `{name}` instead of `\g<name>`.Entire match can be referenced using `{0}`.This makes the template string easier to read and means that it no longer needs to bea raw string.However, `re` template mode can be enabled using `enable_re_template_mode()`.This might be useful if python-pcre is to be used with existing `re`-based code.```python>>> pcre.enable_re_template_mode()>>> pcre.sub(r'(.)', r'[\1]', 'foo')'[f][o][o]'```A function to convert `re` templates is also provided for those one-off cases.```python>>> pcre.convert_re_template(r'static PyObject*\npy_\1(void)\n{')'static PyObject*\npy_{1}(void)\n{{'```A small difference between the two modes is that in `str.format()` mode, groups thatdidn't match are replaced with `''` whereas in `re` mode it's an error to referencesuch groups in the template.Also note that in Python 3.x `bytes.format()` is not available so the template needsto be a `str`.Unicode handling----------------python-pcre internally uses the UTF-8 interface of the PCRE library.Patterns or matched subjects specified as byte strings that contain ascii charactersonly (0-127) are passed to PCRE directly, as ascii is a subset of UTF-8.Other byte strings are internally re-encoded using a simple Latin1 to UTF-8 codecwhich maps characters 128-255 to unicode codepoints of the same value.This conversion is transparent to the caller.If you know that your byte strings are UTF-8, you can use the `pcre.UTF8` flagto tell python-pcre to pass them directly to PCRE.  This flag has to be specifiedevery time a UTF-8 pattern is compiled or a UTF-8 subject is matched.  Note thatin this mode things like `.` may match multiple bytes:```python>>> pcre.compile('.').match(b'\xc3\x9c', flags=pcre.UTF8).group()b'\xc3\x9c'  # two bytes>>> _.decode('utf-8')u'\xdc'  # one character```python-pcre also accepts unicode strings as input.  In Python 3.3 or newer, whichimplement [PEP 393](http://legacy.python.org/dev/peps/pep-0393/), unicode stringsstored internally as ascii are passed to PCRE directly.  Other internal formats areencoded into UTF-8 using Python APIs (which use the UTF-8 form cached in the unicodeobject if available).  In older Python versions these optimizations are not supportedso all unicode objects require the extra encoding step.python-pcre also accepts objects supporting the buffer interface, such as `array.array`objects.  Supported are both old and new buffer APIs with buffers containing either bytesor unicode characters, with the same UTF-8 encoding strategy as byte/unicode strings.When internally encoding subject strings to UTF-8, any offsets accepted as inputor provided as output are also converted between byte and character offsets so thatthe caller doesn't need to be aware of the conversion -- the offsets are alwaysindexes into the specified subject string, whether it's a byte string or a unicodestring.License-------```Copyright (c) 2012-2015, Arkadiusz WahligAll rights reserved.Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions are met:* Redistributions of source code must retain the above copyrightnotice, this list of conditions and the following disclaimer.* Redistributions in binary form must reproduce the above copyrightnotice, this list of conditions and the following disclaimer in thedocumentation and/or other materials provided with the distribution.* Neither the name of the <organization> nor thenames of its contributors may be used to endorse or promote productsderived from this software without specific prior written permission.THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" ANDANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANYDIRECT, 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 ANDON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.```