\n' % text)
pybtex-0.21/pybtex/backends/__init__.py 0000644 0001750 0001750 00000007660 13040472400 017476 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
import pybtex.io
from pybtex.plugin import Plugin
class BaseBackend(Plugin):
"""This is the base class for the backends. We encourage
you to implement as many of the symbols and tags as
possible when you create a new plugin.
symbols[u'ndash'] : Used to separate pages
symbols[u'newblock'] : Used to separate entries in the bibliography
symbols[u'nbsp'] : A non-breakable space
tags[u'em'] : emphasize text
tags[u'strong'] : emphasize text even more
tags[u'i'] : italicize text, not semantic
tags[u'b'] : embolden text, not semantic
tags[u'tt'] : typewrite text, not semantic
"""
RenderType = basestring #: the result of render and render_sequence
default_suffix = None #: the default suffix for an output file
def __init__(self, encoding=None):
self.encoding = encoding or pybtex.io.get_default_encoding()
def write_prologue(self):
pass
def write_epilogue(self):
pass
def format_str(self, str_):
"""Format the given string *str_*.
The default implementation simply returns the string ad verbatim.
Override this method for non-string backends.
"""
return str_
def format_tag(self, tag_name, text):
"""Format a tag with some text inside.
*tag_name* is a str, and *text* is a rendered Text object.
"""
raise NotImplementedError
def format_href(self, url, text):
"""Format a hyperlink with some text inside.
*url* is a str, and *text* is a rendered Text object.
"""
raise NotImplementedError
def format_protected(self, text):
"""Format a "protected" piece of text.
In LaTeX backend, it is formatted as a {braced group}.
Most other backends would just output the text as-is.
"""
return text
def render_sequence(self, rendered_list):
"""Render a sequence of rendered Text objects.
The default implementation simply concatenates
the strings in rendered_list.
Override this method for non-string backends.
"""
return "".join(rendered_list)
def write_entry(self, label, key, text):
raise NotImplementedError
def write_to_file(self, formatted_entries, filename):
with pybtex.io.open_unicode(filename, "w", self.encoding) as stream:
self.write_to_stream(formatted_entries, stream)
if hasattr(stream, 'getvalue'):
return stream.getvalue()
def write_to_stream(self, formatted_bibliography, stream):
self.output = stream.write
self.formatted_bibliography = formatted_bibliography
self.write_prologue()
for entry in formatted_bibliography:
self.write_entry(entry.key, entry.label, entry.text.render(self))
self.write_epilogue()
pybtex-0.21/pybtex/backends/latex.py 0000644 0001750 0001750 00000006445 13040472400 017054 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
r"""
LaTeX output backend.
>>> from pybtex.richtext import Tag, HRef
>>> latex = Backend()
>>> print Tag('em', '').render(latex)
>>> print Tag('em', 'Non-', 'empty').render(latex)
\emph{Non-empty}
>>> print HRef('/', '').render(latex)
>>> print HRef('/', 'Non-', 'empty').render(latex)
\href{/}{Non-empty}
>>> print HRef('http://example.org/', 'http://example.org/').render(latex)
\url{http://example.org/}
"""
import codecs
import latexcodec # noqa
from pybtex.backends import BaseBackend
class Backend(BaseBackend):
default_suffix = '.bbl'
symbols = {
'ndash': u'--',
'newblock': u'\n\\newblock ',
'nbsp': u'~'
}
tags = {
u'em': u'emph',
u'strong': None,
u'i': u'textit',
u'b': u'textbf',
u'tt': u'texttt'
}
def __init__(self, encoding=None):
super(Backend, self).__init__(encoding)
self.latex_encoding = 'ulatex+' + self.encoding
def format_str(self, str_):
return codecs.encode(str_, self.latex_encoding)
def format_tag(self, tag_name, text):
tag = self.tags.get(tag_name)
if tag is None:
return u'{%s}' % text if text else u''
else:
return ur'\%s{%s}' % (tag, text) if text else u''
def format_href(self, url, text):
if not text:
return ''
elif text == self.format_str(url):
return u'\\url{%s}' % url
else:
return ur'\href{%s}{%s}' % (url, text) if text else u''
def format_protected(self, text):
"""
>>> from pybtex.richtext import Protected
>>> print Protected('CTAN').render_as('latex')
{CTAN}
"""
return '{%s}' % text
def write_prologue(self):
if self.formatted_bibliography.preamble:
self.output(self.formatted_bibliography.preamble + u'\n')
longest_label = self.formatted_bibliography.get_longest_label()
self.output(u'\\begin{thebibliography}{%s}' % longest_label)
def write_epilogue(self):
self.output(u'\n\n\\end{thebibliography}\n')
def write_entry(self, key, label, text):
self.output(u'\n\n\\bibitem[%s]{%s}\n' % (label, key))
self.output(text)
pybtex-0.21/pybtex/backends/plaintext.py 0000644 0001750 0001750 00000003021 13040472400 017732 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from pybtex.backends import BaseBackend
class Backend(BaseBackend):
default_suffix = '.txt'
symbols = {
'ndash': u'-',
'newblock': u' ',
'nbsp': u' '
}
def format_tag(self, tag_name, text):
return text
def format_href(self, url, text):
return text
def write_entry(self, key, label, text):
self.output(u"[%s] " % label)
self.output(text)
self.output(u'\n')
pybtex-0.21/pybtex/scanner.py 0000644 0001750 0001750 00000013714 13040472400 015613 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""Base parser class
"""
import re
from pybtex.exceptions import PybtexError
class Token(object):
def __init__(self, value, pattern):
self.value = value
self.pattern = pattern
def __repr__(self):
return repr(self.value)
class Pattern(object):
def __init__(self, regexp, description, flags=0):
self.description = description
compiled_regexp = re.compile(regexp, flags=flags)
self.search = compiled_regexp.search
self.match = compiled_regexp.match
self.findall = compiled_regexp.findall
class Literal(Pattern):
def __init__(self, literal):
pattern = re.compile(re.escape(literal))
description = u"'{0}'".format(literal)
super(Literal, self).__init__(pattern, description)
class Scanner(object):
text = None
lineno = 1
pos = 0
WHITESPACE = Pattern(ur'\s+', 'whitespace')
NEWLINE = Pattern(ur'\n|(\r\n)|\r', 'newline')
def __init__(self, text, filename=None):
self.text = text
self.end_pos = len(text)
self.filename = filename
def skip_to(self, patterns):
end = None
winning_pattern = None
for pattern in patterns:
match = pattern.search(self.text, self.pos)
if match and (not end or match.end() < end):
end = match.end()
winning_pattern = pattern
if winning_pattern:
value = self.text[self.pos: end]
self.pos = end
# print '>>', value
self.update_lineno(value)
return Token(value, winning_pattern)
def update_lineno(self, value):
num_newlines = len(self.NEWLINE.findall(value))
self.lineno += num_newlines
def eat_whitespace(self):
whitespace = self.WHITESPACE.match(self.text, self.pos)
if whitespace:
self.pos = whitespace.end()
self.update_lineno(whitespace.group())
def eof(self):
return self.pos == self.end_pos
def get_token(self, patterns, allow_eof=False):
self.eat_whitespace()
if self.eof():
if allow_eof:
raise EOFError
else:
raise PrematureEOF(self)
for pattern in patterns:
match = pattern.match(self.text, self.pos)
if match:
value = match.group()
self.pos = match.end()
# print '->', value
return Token(value, pattern)
def optional(self, patterns, allow_eof=False):
return self.get_token(patterns, allow_eof=allow_eof)
def required(self, patterns, description=None, allow_eof=False):
token = self.get_token(patterns, allow_eof=allow_eof)
if token is None:
if not description:
description = ' or '.join(pattern.description for pattern in patterns)
raise TokenRequired(description, self)
else:
return token
def get_error_context_info(self):
return self.lineno, self.pos
def get_error_context(self, context_info):
error_lineno, error_pos = context_info
if error_lineno is not None:
error_lineno0 = error_lineno - 1
lines = self.text.splitlines(True)
before_error = ''.join(lines[:error_lineno0])
colno = error_pos - len(before_error)
context = lines[error_lineno0].rstrip('\r\n')
else:
colno = None
context = None
return context, error_lineno, colno
def get_remainder(self):
return self.text[self.pos:]
class PybtexSyntaxError(PybtexError):
error_type = 'syntax error'
def __init__(self, message, parser):
super(PybtexSyntaxError, self).__init__(message, filename=parser.filename)
self.lineno = parser.lineno
self.parser = parser
self.error_context_info = parser.get_error_context_info()
def __unicode__(self):
base_message = super(PybtexSyntaxError, self).__unicode__()
pos = u' in line {0}'.format(self.lineno) if self.lineno is not None else ''
return u'{error_type}{pos}: {message}'.format(
error_type=self.error_type,
pos=pos,
message=base_message,
)
class PrematureEOF(PybtexSyntaxError):
def __init__(self, parser):
message = 'premature end of file'
super(PrematureEOF, self).__init__(message, parser)
class TokenRequired(PybtexSyntaxError):
def __init__(self, description, parser):
message = u'{0} expected'.format(description)
super(TokenRequired, self).__init__(message, parser)
def get_context(self):
context, lineno, colno = self.parser.get_error_context(self.error_context_info)
if context is None:
return ''
if colno == 0:
marker = '^^'
else:
marker = ' ' * (colno - 1) + '^^^'
return '\n'.join((context, marker))
pybtex-0.21/pybtex/markup/ 0000755 0001750 0001750 00000000000 13040475070 015107 5 ustar and and 0000000 0000000 pybtex-0.21/pybtex/markup/__init__.py 0000644 0001750 0001750 00000005153 13040472400 017216 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from pybtex.scanner import Scanner, Literal, PybtexSyntaxError
from pybtex.richtext import String, Text, Protected
class LaTeXParser(Scanner):
LBRACE = Literal(u'{')
RBRACE = Literal(u'}')
def parse(self, level=0):
"""
>>> from nose.tools import assert_raises
>>> LaTeXParser('abc').parse()
Text('abc')
>>> LaTeXParser('abc{def}').parse()
Text('abc', Protected('def'))
>>> LaTeXParser('abc{def {xyz}} !').parse()
Text('abc', Protected('def ', Protected('xyz')), ' !')
>>> assert_raises(PybtexSyntaxError, LaTeXParser('abc{def}}').parse)
>>> assert_raises(PybtexSyntaxError, LaTeXParser('abc{def}{').parse)
"""
return Text(*self.iter_string_parts(level=level))
def iter_string_parts(self, level=0):
while True:
token = self.skip_to([self.LBRACE, self.RBRACE])
if not token:
remainder = self.get_remainder()
if remainder:
yield String(remainder)
if level != 0:
raise PybtexSyntaxError('unbalanced braces', self)
break
elif token.pattern is self.LBRACE:
yield String(token.value[:-1])
yield Protected(*self.iter_string_parts(level=level + 1))
else: # brace.pattern is self.RBRACE
yield String(token.value[:-1])
if level == 0:
raise PybtexSyntaxError('unbalanced braces', self)
break
pybtex-0.21/pybtex/io.py 0000644 0001750 0001750 00000006243 13040472400 014570 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""Unicode-aware IO routines."""
from __future__ import absolute_import
import io
import sys
from os import path, environ
from pybtex.exceptions import PybtexError
from pybtex.kpathsea import kpsewhich
def get_default_encoding():
return 'UTF-8'
def get_stream_encoding(stream):
stream_encoding = getattr(stream, 'encoding', None)
return stream_encoding or get_default_encoding()
def _open_existing(opener, filename, mode, locate, **kwargs):
if not path.isfile(filename):
found = locate(filename)
if found:
filename = found
return opener(filename, mode, **kwargs)
def _open_or_create(opener, filename, mode, environ, **kwargs):
try:
return opener(filename, mode, **kwargs)
except EnvironmentError as error:
if 'TEXMFOUTPUT' in environ:
new_filename = path.join(environ['TEXMFOUTPUT'], filename)
try:
return opener(new_filename, mode, **kwargs)
except EnvironmentError:
pass
raise error
def _open(opener, filename_or_file, mode, **kwargs):
if hasattr(filename_or_file, 'read') and hasattr(filename_or_file, 'close'):
return filename_or_file
else:
filename = filename_or_file
write_mode = 'w' in mode
try:
if write_mode:
return _open_or_create(opener, filename, mode, environ, **kwargs)
else:
return _open_existing(opener, filename, mode, locate=kpsewhich, **kwargs)
except EnvironmentError as error:
raise PybtexError("unable to open %s. %s" % (filename, error.strerror))
def open_raw(filename, mode='rb', encoding=None):
return _open(io.open, filename, mode)
def open_unicode(filename, mode='r', encoding=None):
if encoding is None:
encoding = get_default_encoding()
return _open(io.open, filename, mode, encoding=encoding)
def reader(stream, encoding=None, errors='strict'):
if encoding is None:
encoding = get_stream_encoding(stream)
return io.TextIOWrapper(stream, encoding=encoding, errors=errors)
stdout = sys.stdout
stderr = sys.stderr
pybtex-0.21/pybtex/richtext.py 0000644 0001750 0001750 00000070720 13040472400 016014 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
r"""(simple but) rich text formatting tools
Usage:
>>> t = Text('this ', 'is a ', Tag('em', 'very'), Text(' rich', ' text'))
>>> print t.render_as('latex')
this is a \emph{very} rich text
>>> print unicode(t)
this is a very rich text
>>> t = t.capitalize().add_period()
>>> print t.render_as('latex')
This is a \emph{very} rich text.
>>> print unicode(t)
This is a very rich text.
>>> print Symbol('ndash').render_as('latex')
--
>>> t = Text('Some ', Tag('em', Text('nested ', Tag('tt', 'Text', Text(' objects')))), '.')
>>> print t.render_as('latex')
Some \emph{nested \texttt{Text objects}}.
>>> print unicode(t)
Some nested Text objects.
>>> t = t.upper()
>>> print t.render_as('latex')
SOME \emph{NESTED \texttt{TEXT OBJECTS}}.
>>> print unicode(t)
SOME NESTED TEXT OBJECTS.
>>> t = Text(', ').join(['one', 'two', Tag('em', 'three')])
>>> print t.render_as('latex')
one, two, \emph{three}
>>> print unicode(t)
one, two, three
>>> t = Text(Symbol('nbsp')).join(['one', 'two', Tag('em', 'three')])
>>> print t.render_as('latex')
one~two~\emph{three}
>>> print unicode(t)
onetwothree
"""
import warnings
import itertools
from abc import ABCMeta, abstractmethod
from pybtex import textutils
from pybtex.utils import deprecated, collect_iterable
# workaround for doctests in Python 2/3
def str_repr(string):
"""
>>> print str_repr('test')
'test'
>>> print str_repr(u'test')
'test'
"""
result = repr(string)
if result.startswith('u'):
return result[1:]
else:
return result
def ensure_text(value):
if isinstance(value, basestring):
return String(value)
elif isinstance(value, BaseText):
return value
else:
bad_type = type(value).__name__
raise ValueError('parts must be strings or BaseText instances, not ' + bad_type)
class BaseText(object):
__metaclass__ = ABCMeta
@abstractmethod
def __unicode__(self):
raise NotImplementedError
@abstractmethod
def __eq__(self, other):
raise NotImplementedError
def __ne__(self, other):
return not self == other
@abstractmethod
def __len__(self):
raise NotImplementedError
@abstractmethod
def __contains__(self, item):
raise NotImplementedError
@abstractmethod
def __getitem__(self, key):
raise NotImplementedError
def __add__(self, other):
"""
Concatenate this Text with another Text or string.
>>> Text('Longcat is ') + Tag('em', 'long')
Text('Longcat is ', Tag('em', 'long'))
"""
return Text(self, other)
def append(self, text):
"""
Append text to the end of this text.
Normally, this is the same as concatenating texts with +,
but for tags and similar objects the appended text is placed _inside_ the tag.
>>> text = Tag('em', 'Look here')
>>> print (text + '!').render_as('html')
Look here!
>>> print text.append('!').render_as('html')
Look here!
"""
return self + text
def join(self, parts):
"""Join a list using this text (like string.join)
>>> letters = ['a', 'b', 'c']
>>> print unicode(String('-').join(letters))
a-b-c
>>> print unicode(String('-').join(iter(letters)))
a-b-c
"""
if not parts:
return Text()
joined = []
for part in parts:
if joined:
joined.append(self)
joined.append(part)
return Text(*joined)
@abstractmethod
def split(self, sep=None, keep_empty_parts=None):
raise NotImplementedError
@abstractmethod
def startswith(self, prefix):
"""
Return True if string starts with the prefix,
otherwise return False.
prefix can also be a tuple of suffixes to look for.
"""
raise NotImplementedError
@abstractmethod
def endswith(self, suffix):
"""
Return True if the string ends with the specified suffix,
otherwise return False.
suffix can also be a tuple of suffixes to look for.
"""
raise NotImplementedError
@abstractmethod
def isalpha(self):
raise NotImplementedError
def add_period(self, period='.'):
"""
Add a period to the end of text, if the last character is not ".", "!" or "?".
>>> text = Text("That's all, folks")
>>> print unicode(text.add_period())
That's all, folks.
>>> text = Text("That's all, folks!")
>>> print unicode(text.add_period())
That's all, folks!
"""
if self and not textutils.is_terminated(self):
return self.append(period)
else:
return self
def abbreviate(self):
def abbreviate_word(word):
if word.isalpha():
return word[0].add_period()
else:
return word
parts = self.split(textutils.delimiter_re)
return String('').join(abbreviate_word(part) for part in parts)
def capfirst(self):
"""
Capitalize the first letter of the text.
>>> Text(Tag('em', 'long Cat')).capfirst()
Text(Tag('em', 'Long Cat'))
"""
return self[:1].upper() + self[1:]
def capitalize(self):
"""
Capitalize the first letter of the text and lowercase the rest.
>>> Text(Tag('em', 'LONG CAT')).capitalize()
Text(Tag('em', 'Long cat'))
"""
return self[:1].upper() + self[1:].lower()
@abstractmethod
def lower(self):
raise NotImplementedError
@abstractmethod
def upper(self):
raise NotImplementedError
@abstractmethod
def render(self, backend):
raise NotImplementedError
def render_as(self, backend_name):
r"""
Render this :py:class:`Text` into markup.
This is a wrapper method that loads a formatting backend plugin
and calls :py:meth:`Text.render`.
>>> text = Text('Longcat is ', Tag('em', 'looooooong'), '!')
>>> print text.render_as('html')
Longcat is looooooong!
>>> print text.render_as('latex')
Longcat is \emph{looooooong}!
>>> print text.render_as('text')
Longcat is looooooong!
:param backend_name: The name of the output backend (like ``"latex"`` or
``"html"``).
"""
from pybtex.plugin import find_plugin
backend_cls = find_plugin('pybtex.backends', backend_name)
return self.render(backend_cls())
def _unpack(self):
"""
For Text object, iterate over all text parts.
Else, yield the object itself.
Used for unpacking Text objects passed as children to another Text object.
"""
yield self
def _typeinfo(self):
"""
Return the type of this object and its parameters
(not including the actual text content).
Used for:
- merging similar tags together (AB -> AB),
- creating similar text objects with different text content.
"""
return None, ()
class BaseMultipartText(BaseText):
info = ()
def __init__(self, *parts):
"""Create a text object consisting of one or more parts.
Empty parts are ignored:
>>> Text() == Text('') == Text('', '', '')
True
>>> Text('Word', '') == Text('Word')
True
Text() objects are unpacked and their children are included directly:
>>> Text(Text('Multi', ' '), Tag('em', 'part'), Text(' ', Text('text!')))
Text('Multi ', Tag('em', 'part'), ' text!')
>>> Tag('strong', Text('Multi', ' '), Tag('em', 'part'), Text(' ', 'text!'))
Tag('strong', 'Multi ', Tag('em', 'part'), ' text!')
Similar objects are merged together:
>>> Text('Multi', Tag('em', 'part'), Text(Tag('em', ' ', 'text!')))
Text('Multi', Tag('em', 'part text!'))
>>> Text('Please ', HRef('/', 'click'), HRef('/', ' here'), '.')
Text('Please ', HRef('/', 'click here'), '.')
"""
parts = (ensure_text(part) for part in parts)
nonempty_parts = (part for part in parts if part)
unpacked_parts = itertools.chain(*[part._unpack() for part in nonempty_parts])
merged_parts = self._merge_similar(unpacked_parts)
self.parts = list(merged_parts)
self.length = sum(len(part) for part in self.parts)
def __unicode__(self):
return ''.join(unicode(part) for part in self.parts)
def __eq__(self, other):
"""
Rich text objects support equality comparison:
>>> Text('Cat') == Text('cat')
False
>>> Text('Cat') == Text('Cat')
True
"""
return (
isinstance(other, BaseText) and
self._typeinfo() == other._typeinfo() and
self.parts == other.parts
)
def __len__(self):
"""
``len(text)`` returns the number of characters in the text, ignoring
the markup:
>>> len(Text('Long cat'))
8
>>> len(Text(Tag('em', 'Long'), ' cat'))
8
>>> len(Text(HRef('http://example.com/', 'Long'), ' cat'))
8
"""
return self.length
def __contains__(self, item):
"""
``value in text`` returns ``True`` if any part of the ``text``
contains the substring ``value``:
>>> 'Long cat' in Text('Long cat!')
True
Substrings splitted across multiple text parts are not matched:
>>> 'Long cat' in Text(Tag('em', 'Long'), 'cat!')
False
"""
if not isinstance(item, basestring):
raise TypeError(item)
return not item or any(part.__contains__(item) for part in self.parts)
def __getitem__(self, key):
"""
Slicing and extracting characters works like with regular strings,
formatting is preserved.
>>> Text('Longcat is ', Tag('em', 'looooooong!'))[:15]
Text('Longcat is ', Tag('em', 'looo'))
>>> Text('Longcat is ', Tag('em', 'looooooong!'))[-1]
Text(Tag('em', '!'))
"""
if isinstance(key, (int, long)):
start = key
end = None
elif isinstance(key, slice):
start, end, step = key.indices(len(self))
if step != 1:
raise NotImplementedError
else:
raise TypeError(key, type(key))
if start < 0:
start = len(self) + start
if end is None:
end = start + 1
if end < 0:
end = len(self) + end
return self._slice_end(len(self) - start)._slice_beginning(end - start)
def _slice_beginning(self, slice_length):
"""
Return a text consistng of the first slice_length characters
of this text (with formatting preserved).
"""
parts = []
length = 0
for part in self.parts:
if length + len(part) > slice_length:
parts.append(part[:slice_length - length])
break
else:
parts.append(part)
length += len(part)
return self._create_similar(parts)
def _slice_end(self, slice_length):
"""
Return a text consistng of the last slice_length characters
of this text (with formatting preserved).
"""
parts = []
length = 0
for part in reversed(self.parts):
if length + len(part) > slice_length:
parts.append(part[len(part) - (slice_length - length):])
break
else:
parts.append(part)
length += len(part)
return self._create_similar(reversed(parts))
def append(self, text):
"""
Append text to the end of this text.
For Tags, HRefs, etc. the appended text is placed *inside* the tag.
>>> text = Tag('strong', 'Chuck Norris')
>>> print (text + ' wins!').render_as('html')
Chuck Norris wins!
>>> print text.append(' wins!').render_as('html')
Chuck Norris wins!
"""
return self._create_similar(self.parts + [text])
@collect_iterable
def split(self, sep=None, keep_empty_parts=None):
"""
>>> Text('a + b').split()
[Text('a'), Text('+'), Text('b')]
>>> Text('a, b').split(', ')
[Text('a'), Text('b')]
"""
if keep_empty_parts is None:
keep_empty_parts = sep is not None
tail = [''] if keep_empty_parts else []
for part in self.parts:
split_part = part.split(sep, keep_empty_parts=True)
if not split_part:
continue
for item in split_part[:-1]:
if tail:
yield self._create_similar(tail + [item])
tail = []
else:
if item or keep_empty_parts:
yield self._create_similar([item])
tail.append(split_part[-1])
if tail:
tail_text = self._create_similar(tail)
if tail_text or keep_empty_parts:
yield tail_text
def startswith(self, prefix):
"""
Return True if the text starts with the given prefix.
>>> Text('Longcat!').startswith('Longcat')
True
Prefixes split across multiple parts are not matched:
>>> Text(Tag('em', 'Long'), 'cat!').startswith('Longcat')
False
"""
if not self.parts:
return False
else:
return self.parts[0].startswith(prefix)
def endswith(self, suffix):
"""
Return True if the text ends with the given suffix.
>>> Text('Longcat!').endswith('cat!')
True
Suffixes split across multiple parts are not matched:
>>> Text('Long', Tag('em', 'cat'), '!').endswith('cat!')
False
"""
if not self.parts:
return False
else:
return self.parts[-1].endswith(suffix)
def isalpha(self):
"""
Return True if all characters in the string are alphabetic and there is
at least one character, False otherwise.
"""
return bool(self) and all(part.isalpha() for part in self.parts)
def lower(self):
"""
Convert rich text to lowercase.
>>> Text(Tag('em', 'Long cat')).lower()
Text(Tag('em', 'long cat'))
"""
return self._create_similar(part.lower() for part in self.parts)
def upper(self):
"""
Convert rich text to uppsercase.
>>> Text(Tag('em', 'Long cat')).upper()
Text(Tag('em', 'LONG CAT'))
"""
return self._create_similar(part.upper() for part in self.parts)
def render(self, backend):
"""
Render this :py:class:`Text` into markup.
:param backend: The formatting backend (an instance of
:py:class:`pybtex.backends.BaseBackend`).
"""
rendered_list = [part.render(backend) for part in self.parts]
assert all(isinstance(item, backend.RenderType)
for item in rendered_list)
return backend.render_sequence(rendered_list)
def _typeinfo(self):
"""Return the type and the parameters used to create this text object.
>>> text = Tag('strong', 'Heavy rain!')
>>> text._typeinfo() == (Tag, ('strong',))
True
"""
return type(self), self.info
def _create_similar(self, parts):
"""
Create a new text object of the same type with the same parameters,
with different text content.
>>> text = Tag('strong', 'Bananas!')
>>> text._create_similar(['Apples!'])
Tag('strong', 'Apples!')
"""
cls, cls_args = self._typeinfo()
args = list(cls_args) + list(parts)
return cls(*args)
def _merge_similar(self, parts):
"""Merge adjacent text objects with the same type and parameters together.
>>> text = Text()
>>> parts = [Tag('em', 'Breaking'), Tag('em', ' '), Tag('em', 'news!')]
>>> list(text._merge_similar(parts))
[Tag('em', 'Breaking news!')]
"""
groups = itertools.groupby(parts, lambda value: value._typeinfo())
for typeinfo, group in groups:
cls, info = typeinfo
group = list(group)
if cls and len(group) > 1:
group_parts = itertools.chain(*(text.parts for text in group))
args = list(info) + list(group_parts)
yield cls(*args)
else:
for text in group:
yield text
@deprecated('0.19', 'use __unicode__() instead')
def plaintext(self):
return unicode(self)
@deprecated('0.19')
def enumerate(self):
for n, child in enumerate(self.parts):
try:
for p in child.enumerate():
yield p
except AttributeError:
yield self, n
@deprecated('0.19')
def reversed(self):
for n, child in reversed(list(enumerate(self.parts))):
try:
for p in child.reversed():
yield p
except AttributeError:
yield self, n
@deprecated('0.19', 'use slicing instead')
def get_beginning(self):
try:
l, i = next(self.enumerate())
except StopIteration:
pass
else:
return l.parts[i]
@deprecated('0.19', 'use slicing instead')
def get_end(self):
try:
l, i = next(self.reversed())
except StopIteration:
pass
else:
return l.parts[i]
@deprecated('0.19', 'use slicing instead')
def apply_to_start(self, f):
return self.map(f, lambda index, length: index == 0)
@deprecated('0.19', 'use slicing instead')
def apply_to_end(self, f):
return self.map(f, lambda index, length: index == length - 1)
@deprecated('0.19')
def map(self, f, condition=None):
if condition is None:
condition = lambda index, length: True
def iter_map_with_condition():
length = len(self)
for index, child in enumerate(self.parts):
if hasattr(child, 'map'):
yield child.map(f, condition) if condition(index, length) else child
else:
yield f(child) if condition(index, length) else child
return self._create_similar(iter_map_with_condition())
class String(BaseText):
"""
A :py:class:`String` is a wrapper for a plain Python string.
>>> from pybtex.richtext import String
>>> print String('Crime & Punishment').render_as('text')
Crime & Punishment
>>> print String('Crime & Punishment').render_as('html')
Crime & Punishment
:py:class:`String` supports the same methods as :py:class:`Text`.
"""
def __init__(self, *parts):
"""
All arguments must be plain unicode strings.
Arguments are concatenated together.
>>> print unicode(String('November', ', ', 'December', '.'))
November, December.
"""
self.value = ''.join(parts)
def __repr__(self):
return str_repr(self.value)
def __unicode__(self):
return unicode(self.value)
def __eq__(self, other):
"""
Compare two :py:class:`.String` objects.
"""
return type(other) == type(self) and self.value == other.value
def __len__(self):
return self.value.__len__()
def __contains__(self, item):
return self.value.__contains__(item)
def __getitem__(self, index):
return String(self.value.__getitem__(index))
def __add__(self, other):
return BaseText.__add__(self, other)
def split(self, sep=None, keep_empty_parts=None):
if keep_empty_parts is None:
keep_empty_parts = sep is not None
if sep is None:
from .textutils import whitespace_re
parts = whitespace_re.split(self.value)
elif isinstance(sep, basestring):
parts = self.value.split(sep)
else:
try:
split_method = sep.split
except AttributeError:
raise TypeError('sep must be None, string or compiled regular expression')
else:
parts = split_method(self.value)
return [String(part) for part in parts if part or keep_empty_parts]
def startswith(self, prefix):
"""
Return True if string starts with the prefix,
otherwise return False.
prefix can also be a tuple of suffixes to look for.
"""
return self.value.startswith(prefix)
def endswith(self, suffix):
"""
Return True if the string ends with the specified suffix,
otherwise return False.
suffix can also be a tuple of suffixes to look for.
return self.value.endswith(text)
"""
return self.value.endswith(suffix)
def isalpha(self):
return self.value.isalpha()
def lower(self):
return String(self.value.lower())
def upper(self):
return String(self.value.upper())
@property
def parts(self):
return [unicode(self)]
def _typeinfo(self):
return String, ()
def render(self, backend):
return backend.format_str(self.value)
class Text(BaseMultipartText):
"""
The :py:class:`Text` class is the top level container that may contain
:py:class:`String`, :py:class:`Tag` or :py:class:`HRef` objects.
"""
def __repr__(self):
return 'Text({})'.format(', '.join(repr(part) for part in self.parts))
def _unpack(self):
for part in self.parts:
yield part
@classmethod
def from_latex(cls, latex):
import codecs
import latexcodec # noqa
from pybtex.markup import LaTeXParser
return LaTeXParser(codecs.decode(latex, 'ulatex')).parse()
class Tag(BaseMultipartText):
r"""
A :py:class:`Tag` represents something like an HTML tag
or a LaTeX formatting command:
>>> from pybtex.richtext import Tag
>>> tag = Tag('em', 'The TeXbook')
>>> print tag.render_as('html')
The TeXbook
>>> print tag.render_as('latex')
\emph{The TeXbook}
:py:class:`Tag` supports the same methods as :py:class:`Text`.
"""
def __check_name(self, name):
depr_map = {}
depr_map[u'emph'] = u'em'
if name in depr_map:
msg = u"The tag '%s' is deprecated" % name
msg += u", use '%s' instead." % depr_map[name]
warnings.warn(msg, DeprecationWarning, stacklevel=3)
return depr_map[name]
return name
def __init__(self, name, *args):
if not isinstance(name, (basestring, Text)):
raise ValueError(
"name must be str or Text (got %s)" % name.__class__.__name__)
self.name = self.__check_name(unicode(name))
self.info = self.name,
super(Tag, self).__init__(*args)
def __repr__(self):
if self.parts:
reprparts = ', '.join(repr(part) for part in self.parts)
return 'Tag({}, {})'.format(str_repr(self.name), reprparts)
else:
return 'Tag({})'.format(str_repr(self.name))
def render(self, backend):
text = super(Tag, self).render(backend)
return backend.format_tag(self.name, text)
class HRef(BaseMultipartText):
r"""
A :py:class:`HRef` represends a hyperlink:
>>> from pybtex.richtext import Tag
>>> href = HRef('http://ctan.org/', 'CTAN')
>>> print href.render_as('html')
CTAN
>>> print href.render_as('latex')
\href{http://ctan.org/}{CTAN}
>>> href = HRef(String('http://ctan.org/'), String('http://ctan.org/'))
>>> print href.render_as('latex')
\url{http://ctan.org/}
:py:class:`HRef` supports the same methods as :py:class:`Text`.
"""
def __init__(self, url, *args):
if not isinstance(url, (basestring, BaseText)):
raise ValueError(
"url must be str or Text (got %s)" % url.__class__.__name__)
self.url = unicode(url)
self.info = self.url,
super(HRef, self).__init__(*args)
def __repr__(self):
reprparts = ', '.join(repr(part) for part in self.parts)
return 'HRef({}, {})'.format(str_repr(self.url), reprparts)
def render(self, backend):
text = super(HRef, self).render(backend)
return backend.format_href(self.url, text)
class Protected(BaseMultipartText):
r"""
A :py:class:`Protected` represents a "protected" piece of text.
- :py:meth:`Protected.lower`, :py:meth:`Protected.upper`,
:py:meth:`Protected.capitalize`, and :py:meth:`Protected.capitalize()`
are no-ops and just return the :py:class:`Protected` object itself.
- :py:meth:`Protected.split` never splits the text. It always returns a
one-element list containing the :py:class:`Protected` object itself.
- In LaTeX output, :py:class:`Protected` is {surrounded by braces}. HTML
and plain text backends just output the text as-is.
>>> from pybtex.richtext import Protected
>>> text = Protected('The CTAN archive')
>>> text.lower()
Protected('The CTAN archive')
>>> text.split()
[Protected('The CTAN archive')]
>>> print text.render_as('latex')
{The CTAN archive}
>>> print text.render_as('html')
The CTAN archive
.. versionadded:: 0.20
"""
def __init__(self, *args):
super(Protected, self).__init__(*args)
def __repr__(self):
reprparts = ', '.join(repr(part) for part in self.parts)
return 'Protected({})'.format(reprparts)
def capfirst(self):
return self
def capitalize(self):
return self
def lower(self):
return self
def upper(self):
return self
def split(self, sep=None, keep_empty_parts=None):
return [self]
def render(self, backend):
text = super(Protected, self).render(backend)
return backend.format_protected(text)
class Symbol(BaseText):
"""A special symbol. This class is rarely used and may be removed in
future versions.
Examples of special symbols are non-breaking spaces and dashes.
:py:class:`Symbol` supports the same methods as :py:class:`Text`.
"""
def __init__(self, name):
self.name = name
self.info = self.name,
def __len__(self):
return 1
def __repr__(self):
return "Symbol(%s)" % str_repr(self.name)
def __unicode__(self):
# XXX
return u'<%s>' % self.name
def __eq__(self, other):
return self.name == other.name
def __contains__(self, item):
return False
def __getitem__(self, index):
# mimic the behavior of a 1-element string
try:
result = 'a'[index]
except IndexError:
raise IndexError('richtext.Symbol index out of range')
else:
return self if result else String()
def split(self, sep=None, keep_empty_parts=None):
return [self]
def startswith(self, text):
return False
def endswith(self, text):
return False
def isalpha(self):
return False
def render(self, backend):
return backend.symbols[self.name]
def upper(self):
return self
def lower(self):
return self
nbsp = Symbol('nbsp')
pybtex-0.21/pybtex/auxfile.py 0000644 0001750 0001750 00000011254 13040472400 015614 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""parse LaTeX aux file
"""
from __future__ import with_statement
import re
import pybtex.io
from pybtex.exceptions import PybtexError
from pybtex.errors import report_error
class AuxDataError(PybtexError):
def __init__(self, message, context=None):
super(AuxDataError, self).__init__(message, context.filename)
self.context = context
def get_context(self):
if self.context.line:
marker = '^' * len(self.context.line)
return self.context.line + '\n' + marker
def __unicode__(self):
base_message = super(AuxDataError, self).__unicode__()
lineno = self.context.lineno
location = 'in line {0}: '.format(lineno) if lineno else ''
return location + base_message
class AuxDataContext(object):
lineno = None
line = None
filename = None
def __init__(self, filename):
self.filename = filename
class AuxData(object):
command_re = re.compile(r'\\(citation|bibdata|bibstyle|@input){(.*)}')
context = None
style = None
data = None
citations = None
def __init__(self, encoding):
self.encoding = encoding
self.citations = []
self._canonical_keys = {}
def handle_citation(self, keys):
for key in keys.split(','):
key_lower = key.lower()
if key_lower in self._canonical_keys:
existing_key = self._canonical_keys[key_lower]
if key != existing_key:
msg = 'case mismatch error between cite keys {0} and {1}'
report_error(AuxDataError(msg.format(key, existing_key), self.context))
self.citations.append(key)
self._canonical_keys[key_lower] = key
def handle_bibstyle(self, style):
if self.style is not None:
report_error(AuxDataError(r'illegal, another \bibstyle command', self.context))
else:
self.style = style
def handle_bibdata(self, bibdata):
if self.data is not None:
report_error(AuxDataError(r'illegal, another \bibdata command', self.context))
else:
self.data = bibdata.split(',')
def handle_input(self, filename):
self.parse_file(filename, toplevel=False)
def handle_command(self, command, value):
action = getattr(self, 'handle_%s' % command.lstrip('@'))
action(value)
def parse_line(self, line, lineno):
self.context.lineno = lineno
self.context.line = line.strip()
match = self.command_re.match(line)
if match:
command, value = match.groups()
self.handle_command(command, value)
def parse_file(self, filename, toplevel=True):
previous_context = self.context
self.context = AuxDataContext(filename)
with pybtex.io.open_unicode(filename, encoding=self.encoding) as aux_file:
for lineno, line in enumerate(aux_file, 1):
self.parse_line(line, lineno)
if previous_context:
self.context = previous_context
else:
self.context.line = None
self.context.lineno = None
# these errors are fatal - always raise an exception instead of using
# erorrs.report_error()
if toplevel and self.data is None:
raise AuxDataError(r'found no \bibdata command', self.context)
if toplevel and self.style is None:
raise AuxDataError(r'found no \bibstyle command', self.context)
def parse_file(filename, encoding=None):
"""Parse a file and return an AuxData object."""
data = AuxData(encoding)
data.parse_file(filename)
return data
pybtex-0.21/pybtex/plugin/ 0000755 0001750 0001750 00000000000 13040475070 015106 5 ustar and and 0000000 0000000 pybtex-0.21/pybtex/plugin/__init__.py 0000644 0001750 0001750 00000014344 13040472400 017217 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
# Copyright (c) 2014 Matthias C. M. Troffaes
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
import os.path # splitext
import pkg_resources
from pybtex.exceptions import PybtexError
class Plugin(object):
pass
#: default pybtex plugins
_DEFAULT_PLUGINS = {
"pybtex.database.input": "bibtex",
"pybtex.database.output": "bibtex",
"pybtex.backends": "latex",
"pybtex.style.labels": "number",
"pybtex.style.names": "plain",
"pybtex.style.sorting": "none",
"pybtex.style.formatting": "unsrt",
}
class PluginGroupNotFound(PybtexError):
def __init__(self, group_name):
message = u'plugin group {group_name} not found'.format(
group_name=group_name,
)
super(PluginGroupNotFound, self).__init__(message)
class PluginNotFound(PybtexError):
def __init__(self, plugin_group, name):
if not name.startswith('.'):
message = u'plugin {plugin_group}.{name} not found'.format(
plugin_group=plugin_group,
name=name,
)
else:
assert plugin_group.endswith('.suffixes')
message = (
u'plugin {plugin_group} for suffix {suffix} not found'.format(
plugin_group=plugin_group,
suffix=name,
)
)
super(PluginNotFound, self).__init__(message)
def _load_entry_point(group, name, use_aliases=False):
groups = [group, group + '.aliases'] if use_aliases else [group]
for search_group in groups:
for entry_point in pkg_resources.iter_entry_points(search_group, name):
return entry_point.load()
raise PluginNotFound(group, name)
def find_plugin(plugin_group, name=None, filename=None):
"""Find a :class:`Plugin` class within *plugin_group* which
matches *name*, or *filename* if *name* is not specified, or
the default plugin if neither *name* nor *filename* is
specified.
If *name* is specified, return the :class:`Plugin` class
registered under *name*. If *filename* is specified, look at
its suffix (i.e. extension) and return the :class:`Plugin`
class registered for this suffix.
If *name* is not a string, but a plugin class, just return it back.
(Used to make functions like :function:`make_bibliography` accept already
loaded plugins as well as plugin names.
"""
if isinstance(name, type) and issubclass(name, Plugin):
return name
if plugin_group not in _DEFAULT_PLUGINS:
raise PluginGroupNotFound(plugin_group)
if name:
return _load_entry_point(plugin_group, name, use_aliases=True)
elif filename:
suffix = os.path.splitext(filename)[1]
return _load_entry_point(plugin_group + '.suffixes', suffix)
else:
return _load_entry_point(plugin_group, _DEFAULT_PLUGINS[plugin_group])
def enumerate_plugin_names(plugin_group):
"""Enumerate all plugin names for the given *plugin_group*."""
return (entry_point.name
for entry_point in pkg_resources.iter_entry_points(plugin_group))
class _FakeEntryPoint(pkg_resources.EntryPoint):
def __init__(self, name, klass):
self.name = name
self.klass = klass
def __str__(self):
return "%s = :%s" % (self.name, self.klass.__name__)
def __repr__(self):
return (
"_FakeEntryPoint(name=%r, klass=%s)"
% (self.name, self.klass.__name__))
def load(self, require=True, env=None, installer=None):
return self.klass
def require(self, env=None, installer=None):
pass
def register_plugin(plugin_group, name, klass, force=False):
"""Register a plugin on the fly.
This works by adding *klass* as a pybtex entry point, under entry
point group *plugin_group* and entry point name *name*.
To register a suffix, append ".suffixes" to the plugin group, and
*name* is then simply the suffix, which should start with a
period.
To register an alias plugin name, append ".aliases" to the plugin group.
Aliases work just as real names, but are not returned by
:function:`enumerate_plugin_names` and not advertised in the command line
help.
If *force* is ``False``, then existing entry points are not
overwritten. If an entry point with the given group and name
already exists, then returns ``False``, otherwise returns
``True``.
If *force* is ``True``, then existing entry points are
overwritten, and the function always returns ``True``.
"""
if plugin_group.endswith(".suffixes"):
base_group, _ = plugin_group.rsplit(".", 1)
if not name.startswith('.'):
raise ValueError("a suffix must start with a period")
elif plugin_group.endswith(".aliases"):
base_group, _ = plugin_group.rsplit(".", 1)
else:
base_group = plugin_group
if base_group not in _DEFAULT_PLUGINS:
raise PluginGroupNotFound(base_group)
dist = pkg_resources.get_distribution('pybtex')
ep_map = pkg_resources.get_entry_map(dist)
if plugin_group not in ep_map:
ep_map[plugin_group] = {}
if name in ep_map[plugin_group] and not force:
return False
else:
ep_map[plugin_group][name] = _FakeEntryPoint(name, klass)
return True
pybtex-0.21/setup.cfg 0000644 0001750 0001750 00000000242 13040472403 014111 0 ustar and and 0000000 0000000 [sdist]
formats = gztar bztar zip
[nosetests]
with-doctest = True
[pytest]
testpaths = pybtex
addopts = --doctest-modules
[upload_docs]
upload_dir = docs/site
pybtex-0.21/tox.ini 0000644 0001750 0001750 00000000160 12675501171 013612 0 ustar and and 0000000 0000000 [testenv]
deps = -rtest_requirements.txt
changedir = {toxworkdir}
commands = nosetests -v --with-doctest pybtex
pybtex-0.21/PKG-INFO 0000644 0001750 0001750 00000003727 13040475070 013403 0 ustar and and 0000000 0000000 Metadata-Version: 1.1
Name: pybtex
Version: 0.21
Summary: A BibTeX-compatible bibliography processor in Python
Home-page: https://pybtex.org/
Author: Andrey Golovizin
Author-email: ag@sologoc.com
License: MIT
Description: BibTeX-compatible bibliography processor in Python
==================================================
Synopsis
--------
::
latex foo.tex
pybtex foo.aux
latex foo.tex
latex foo.tex
Description
-----------
Pybtex reads citation information from a file and
produces a formatted bibliography. BibTeX style files are supported.
Alternatively it is possible to write styles in Python.
Pybtex currently understands the following bibliography formats:
- BibTeX
- BibTeXML
- YAML-based format
The resulting bibliography may be output in one of the following formats
(not supported by legacy BibTeX styles):
- LaTeX
- HTML
- markdown
- plain text
See also
--------
- `Home page `_
- `Pybtex at Bitbucket `_
- `Pybtex at PyPI `_
Platform: platform-independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Text Processing :: Markup :: XML
Classifier: Topic :: Utilities
pybtex-0.21/custom_fixers/ 0000755 0001750 0001750 00000000000 13040475070 015167 5 ustar and and 0000000 0000000 pybtex-0.21/custom_fixers/fix_alt_unicode.py 0000644 0001750 0001750 00000000525 13040464037 020700 0 ustar and and 0000000 0000000 # Taken from jinja2. Thanks, Armin Ronacher.
# See also http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide
from lib2to3 import fixer_base
class FixAltUnicode(fixer_base.BaseFix):
PATTERN = "'__unicode__'"
def transform(self, node, results):
new = node.clone()
new.value = '__str__'
return new
pybtex-0.21/custom_fixers/__init__.py 0000644 0001750 0001750 00000000000 13040464037 017267 0 ustar and and 0000000 0000000 pybtex-0.21/docs/ 0000755 0001750 0001750 00000000000 13040475070 013225 5 ustar and and 0000000 0000000 pybtex-0.21/docs/Makefile 0000644 0001750 0001750 00000017045 13040472400 014666 0 ustar and and 0000000 0000000 # makefile for sphinx documentation
#
# you can set these variables from the command line.
sphinxopts =
sphinxbuild = sphinx-build
paper =
builddir = build
# user-friendly check for sphinx-build
ifeq ($(shell which $(sphinxbuild) >/dev/null 2>&1; echo $$?), 1)
$(error the '$(sphinxbuild)' command was not found. make sure you have sphinx installed, then set the sphinxbuild environment variable to point to the full path of the '$(sphinxbuild)' executable. alternatively you can add the directory with the executable to your path. if you don't have sphinx installed, grab it from http://sphinx-doc.org/)
endif
# internal variables.
paperopt_a4 = -d latex_paper_size=a4
paperopt_letter = -d latex_paper_size=letter
allsphinxopts = -d $(builddir)/doctrees $(paperopt_$(paper)) $(sphinxopts) source
sitesphinxopts = -d $(builddir)/site-doctrees $(paperopt_$(paper)) $(sphinxopts) site
# the i18n builder cannot share the environment and doctrees with the others
i18nsphinxopts = $(paperopt_$(paper)) $(sphinxopts) source
.PHONY: help clean html site dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext upload-docs upload-site upload
help:
@echo "please use \`make ' where is one of"
@echo " html to make standalone html files"
@echo " dirhtml to make html files named index.html in directories"
@echo " singlehtml to make a single large html file"
@echo " pickle to make pickle files"
@echo " json to make json files"
@echo " htmlhelp to make html files and a html help project"
@echo " qthelp to make html files and a qthelp project"
@echo " devhelp to make html files and a devhelp project"
@echo " epub to make an epub"
@echo " latex to make latex files, you can set paper=a4 or paper=letter"
@echo " latexpdf to make latex files and run them through pdflatex"
@echo " latexpdfja to make latex files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make texinfo files"
@echo " info to make texinfo files and run them through makeinfo"
@echo " gettext to make po message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make docutils-native xml files"
@echo " pseudoxml to make pseudoxml-xml files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(builddir)/*
html:
$(sphinxbuild) -b html $(allsphinxopts) $(builddir)/html
@echo
@echo "build finished. the html pages are in $(builddir)/html."
site:
$(sphinxbuild) -b html $(sitesphinxopts) $(builddir)/site
@echo
@echo "build finished. the site pages are in $(builddir)/site."
dirhtml:
$(sphinxbuild) -b dirhtml $(allsphinxopts) $(builddir)/dirhtml
@echo
@echo "build finished. the html pages are in $(builddir)/dirhtml."
singlehtml:
$(sphinxbuild) -b singlehtml $(allsphinxopts) $(builddir)/singlehtml
@echo
@echo "build finished. the html page is in $(builddir)/singlehtml."
pickle:
$(sphinxbuild) -b pickle $(allsphinxopts) $(builddir)/pickle
@echo
@echo "build finished; now you can process the pickle files."
json:
$(sphinxbuild) -b json $(allsphinxopts) $(builddir)/json
@echo
@echo "build finished; now you can process the json files."
htmlhelp:
$(sphinxbuild) -b htmlhelp $(allsphinxopts) $(builddir)/htmlhelp
@echo
@echo "build finished; now you can run html help workshop with the" \
".hhp project file in $(builddir)/htmlhelp."
qthelp:
$(sphinxbuild) -b qthelp $(allsphinxopts) $(builddir)/qthelp
@echo
@echo "build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(builddir)/qthelp, like this:"
@echo "# qcollectiongenerator $(builddir)/qthelp/pybtex.qhcp"
@echo "to view the help file:"
@echo "# assistant -collectionfile $(builddir)/qthelp/pybtex.qhc"
devhelp:
$(sphinxbuild) -b devhelp $(allsphinxopts) $(builddir)/devhelp
@echo
@echo "build finished."
@echo "to view the help file:"
@echo "# mkdir -p $$home/.local/share/devhelp/pybtex"
@echo "# ln -s $(builddir)/devhelp $$home/.local/share/devhelp/pybtex"
@echo "# devhelp"
epub:
$(sphinxbuild) -b epub $(allsphinxopts) $(builddir)/epub
@echo
@echo "build finished. the epub file is in $(builddir)/epub."
latex:
$(sphinxbuild) -b latex $(allsphinxopts) $(builddir)/latex
@echo
@echo "build finished; the latex files are in $(builddir)/latex."
@echo "run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(sphinxbuild) -b latex $(allsphinxopts) $(builddir)/latex
@echo "running latex files through pdflatex..."
$(make) -c $(builddir)/latex all-pdf
@echo "pdflatex finished; the pdf files are in $(builddir)/latex."
latexpdfja:
$(sphinxbuild) -b latex $(allsphinxopts) $(builddir)/latex
@echo "running latex files through platex and dvipdfmx..."
$(make) -c $(builddir)/latex all-pdf-ja
@echo "pdflatex finished; the pdf files are in $(builddir)/latex."
text:
$(sphinxbuild) -b text $(allsphinxopts) $(builddir)/text
@echo
@echo "build finished. the text files are in $(builddir)/text."
man:
$(sphinxbuild) -b man $(allsphinxopts) $(builddir)/man
@echo
@echo "build finished. the manual pages are in $(builddir)/man."
texinfo:
$(sphinxbuild) -b texinfo $(allsphinxopts) $(builddir)/texinfo
@echo
@echo "build finished. the texinfo files are in $(builddir)/texinfo."
@echo "run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(sphinxbuild) -b texinfo $(allsphinxopts) $(builddir)/texinfo
@echo "running texinfo files through makeinfo..."
make -c $(builddir)/texinfo info
@echo "makeinfo finished; the info files are in $(builddir)/texinfo."
gettext:
$(sphinxbuild) -b gettext $(i18nsphinxopts) $(builddir)/locale
@echo
@echo "build finished. the message catalogs are in $(builddir)/locale."
changes:
$(sphinxbuild) -b changes $(allsphinxopts) $(builddir)/changes
@echo
@echo "the overview file is in $(builddir)/changes."
linkcheck: linkcheck-site linkcheck-docs
linkcheck-docs:
$(sphinxbuild) -b linkcheck $(allsphinxopts) $(builddir)/linkcheck
@echo
@echo "link check complete; look for any errors in the above output " \
"or in $(builddir)/linkcheck/output.txt."
linkcheck-site:
$(sphinxbuild) -b linkcheck $(sitesphinxopts) $(builddir)/linkcheck
@echo
@echo "link check complete; look for any errors in the above output " \
"or in $(builddir)/linkcheck/output.txt."
doctest:
$(sphinxbuild) -b doctest $(allsphinxopts) $(builddir)/doctest
@echo "testing of doctests in the sources finished, look at the " \
"results in $(builddir)/doctest/output.txt."
xml:
$(sphinxbuild) -b xml $(allsphinxopts) $(builddir)/xml
@echo
@echo "build finished. the xml files are in $(builddir)/xml."
pseudoxml:
$(sphinxbuild) -b pseudoxml $(allsphinxopts) $(builddir)/pseudoxml
@echo
@echo "build finished. the pseudo-xml files are in $(builddir)/pseudoxml."
# https://pybtex.org/ stuff
RSYNC = rsync -rv --delete
RSYNC_SERVER = www-pybtex@sologoc.com
upload-docs: html
$(RSYNC) $(builddir)/html/ $(RSYNC_SERVER):docs/html/
surge $(builddir)/html/ docs.pybtex.org
(cd .. && ./setup.py upload_docs --upload-dir docs/$(builddir)/html)
upload-site: site
$(RSYNC) $(builddir)/site/ $(RSYNC_SERVER):www/html/
surge $(builddir)/site/ pybtex.org
upload: upload-site upload-docs
pybtex-0.21/docs/pybtex_doctools/ 0000755 0001750 0001750 00000000000 13040475070 016446 5 ustar and and 0000000 0000000 pybtex-0.21/docs/pybtex_doctools/man.py 0000644 0001750 0001750 00000011047 13040472400 017570 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# Based on autodoc_man.py from bzr-1.16.1.
"""Generate man pages for pybtex and pybtex-convert.
"""
from __future__ import with_statement, print_function
import os
import sys
from datetime import datetime
from pybtex import __version__
def man_escape(string):
"""Escapes strings for man page compatibility"""
result = string.replace("\\","\\\\")
result = result.replace("`","\\`")
result = result.replace("-","\\-")
return result
def format_synopsis(main_obj):
yield '.SH "SYNOPSIS"'
yield '.B "%s"' % main_obj.prog
for part in format_args(main_obj):
yield part
def format_args(main_obj):
for arg in main_obj.args.split():
if arg.startswith('[') and arg.endswith(']'):
yield '['
yield '.I "%s"' % arg[1:-1]
yield ']'
else:
yield '.I "%s"' % arg
def format_description(main_obj):
yield '.SH "DESCRIPTION"'
yield main_obj.long_description
def format_help(main_obj):
opt_parser = main_obj.opt_parser
for part in format_option_group(opt_parser, 'general optons', opt_parser.option_list):
yield part
for option_group in opt_parser.option_groups:
for part in format_option_group(opt_parser, option_group.title, option_group.option_list):
yield part
def format_option_group(opt_parser, name, options):
yield '.SH "%s"' % name.upper()
for option in options:
for part in format_option(opt_parser, option):
yield part
def format_option(opt_parser, option):
yield '.TP'
yield '.B "%s"' % opt_parser.formatter.format_option_strings(option)
if option.help:
yield opt_parser.formatter.expand_default(option)
man_head = r"""
.\"Man page for Pybtex (%(cmd)s)
.\"
.\" Generation time: %(timestamp)s
.\" Large parts of this file are autogenerated from the output of
.\" "%(cmd)s --help"
.\"
.TH %(cmd)s 1 "%(datestamp)s" "%(version)s" "Pybtex"
.SH "NAME"
%(cmd)s - %(description)s
""".strip()
def format_head(main_obj):
now = datetime.utcnow()
yield man_head % {
'cmd': main_obj.prog,
'version': __version__,
'description': main_obj.description,
'datestamp': now.strftime('%Y-%m-%d'),
'timestamp': now.strftime('%Y-%m-%d %H:%M:%S +0000'),
}
def format_see_also(main_obj):
yield '.SH "SEE ALSO"'
yield '.UR https://pybtex.org/'
yield '.BR https://pybtex.org/'
def write_manpage(outfile, main_obj):
"""Assembles a man page"""
write(outfile, format_head(main_obj), escape=False)
write(outfile, format_synopsis(main_obj))
write(outfile, format_description(main_obj))
write(outfile, format_help(main_obj))
write(outfile, format_see_also(main_obj))
def write(outfile, lines, escape=True):
for line in lines:
outfile.write(man_escape(line) if escape else line)
outfile.write('\n')
def generate_manpage(man_dir, main_obj):
man_filename = os.path.join(man_dir, '%s.1' % main_obj.prog)
print('Writing', man_filename, file=sys.stderr)
with open(man_filename, 'w') as man_file:
write_manpage(man_file, main_obj)
def generate_manpages(doc_dir):
man_dir = os.path.join(doc_dir, 'man1')
from pybtex.__main__ import main as pybtex
from pybtex.database.convert.__main__ import main as pybtex_convert
from pybtex.database.format.__main__ import main as pybtex_format
generate_manpage(man_dir, pybtex)
generate_manpage(man_dir, pybtex_convert)
generate_manpage(man_dir, pybtex_format)
pybtex-0.21/docs/pybtex_doctools/__init__.py 0000644 0001750 0001750 00000002635 13040472400 020557 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from pkg_resources import get_distribution, EntryPoint
def add_entry_point(group, name, module, attr):
pybtex_dist = get_distribution('pybtex')
entry_point = EntryPoint(name, module, (attr,), dist=pybtex_dist)
entry_point_map = pybtex_dist.get_entry_map()
entry_point_map.setdefault(group, {})[name] = entry_point
pybtex-0.21/docs/pybtex_doctools/pygments.py 0000644 0001750 0001750 00000016362 13040472400 020670 0 ustar and and 0000000 0000000 # Copyright (c) 2006-2017 Andrey Golovigin
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from __future__ import absolute_import
import re
from string import ascii_letters, digits
from pygments.style import Style
from pygments.lexer import RegexLexer, ExtendedRegexLexer, include, default, words
from pygments.token import Keyword, Name, Comment, String, Error, \
Number, Operator, Generic, Literal, Punctuation, Text
from pybtex.database.input.bibtex import NAME_CHARS
from . import add_entry_point
class PybtexStyle(Style):
"""
Port of the default trac highlighter design.
"""
default_style = ''
styles = {
Comment: 'italic #999999',
# Comment.Preproc: 'bold noitalic #999999',
# Comment.Special: 'bold #999999',
Operator: 'bold',
String: '#609000',
Number: '#609000',
String.Escape: '#a10',
Keyword: 'bold',
# Keyword.Type: '#445588',
Name.Builtin: 'bold',
Name.Function: 'bold #840',
Name.Class: 'bold #b30',
Name.Exception: 'bold #b30',
Name.Decorator: '#A20',
Name.Namespace: '#A20',
Name.Label: '#840',
# Name.Variable: '#088',
# Name.Constant: '#088',
Name.Tag: '#666',
# Name.Entity: '#800080',
# used by YAML lexer
Literal.Scalar.Plain: '',
Punctuation.Indicator: '#888',
# Generic.Heading: '#999999',
# Generic.Subheading: '#aaaaaa',
# Generic.Deleted: 'bg:#ffdddd #000000',
# Generic.Inserted: 'bg:#ddffdd #000000',
Generic.Error: '#aa0000',
Generic.Emph: 'italic',
Generic.Strong: 'bold',
Generic.Prompt: '#666',
Generic.Output: '#666',
Generic.Traceback: '#aa0000',
Error: 'bg:#e3d2d2 #a61717'
}
class BibTeXLexer(ExtendedRegexLexer):
name = 'BibTeX'
aliases = ['bibtex', 'bibtex-pybtex']
filenames = ['*.bib']
flags = re.IGNORECASE
IDENTIFIER = ur'[{0}][{1}]*'.format(re.escape(NAME_CHARS), re.escape(NAME_CHARS + digits))
def open_brace_callback(self, match, ctx):
opening_brace = match.group()
ctx.opening_brace = opening_brace
yield match.start(), Text.Punctuation, opening_brace
ctx.pos = match.end()
def close_brace_callback(self, match, ctx):
closing_brace = match.group()
if (
ctx.opening_brace == '{' and closing_brace != '}' or
ctx.opening_brace == '(' and closing_brace != ')'
):
yield match.start(), Error, closing_brace
else:
yield match.start(), Text.Punctuation, closing_brace
del ctx.opening_brace
ctx.pos = match.end()
tokens = {
'root': [
include('whitespace'),
('@comment', Comment),
('@preamble', Name.Class, ('closing-brace', 'value', 'opening-brace')),
('@string', Name.Class, ('closing-brace', 'field', 'opening-brace')),
('@' + IDENTIFIER, Name.Class, ('closing-brace', 'command-body', 'opening-brace')),
('.+', Comment),
],
'opening-brace': [
include('whitespace'),
(r'[\{\(]', open_brace_callback, '#pop'),
],
'closing-brace': [
include('whitespace'),
(r'[\}\)]', close_brace_callback, '#pop'),
],
'command-body': [
include('whitespace'),
(r'[^\s\,\}]+', Name.Label, ('#pop', 'fields')),
],
'fields': [
include('whitespace'),
(',', Text.Punctuation, 'field'),
default('#pop'),
],
'field': [
include('whitespace'),
(IDENTIFIER, Text.Punctuation, ('value', '=')),
default('#pop'),
],
'=': [
include('whitespace'),
('=', Text.Punctuation, '#pop'),
],
'value': [
include('whitespace'),
(IDENTIFIER, Name.Variable),
('"', String, 'quoted-string'),
(r'\{', String, 'braced-string'),
(r'[\d]+', Number),
('#', Text.Punctuation),
default('#pop'),
],
'quoted-string': [
(r'\{', String, 'braced-string'),
('"', String, '#pop'),
('[^\{\"]+', String),
],
'braced-string': [
(r'\{', String, '#push'),
(r'\}', String, '#pop'),
('[^\{\}]+', String),
],
'whitespace': [
(r'\s+', Text),
],
}
class BSTLexer(RegexLexer):
name = 'BST'
aliases = ['bst', 'bst-pybtex']
filenames = ['*.bst']
flags = re.IGNORECASE | re.MULTILINE
tokens = {
'root': [
include('whitespace'),
(words(['read', 'sort']), Name.Class),
(words(['execute', 'integers', 'iterate', 'reverse', 'strings']), Name.Class, ('group')),
(words(['function', 'macro']), Name.Class, ('group', 'group')),
(words(['entry']), Name.Class, ('group', 'group', 'group')),
],
'group': [
include('whitespace'),
('{', Text.Punctuation, ('#pop', 'group-end', 'body')),
],
'group-end': [
include('whitespace'),
('}', Text.Punctuation, '#pop'),
],
'body': [
include('whitespace'),
(r'[^#\"\{\}\s]+\$', Name.Builtin),
(r'[^#\"\{\}\s]+', Name.Variable),
(r'"[^\"]*"', String),
(ur'#-?\d+', Number),
('{', Text.Punctuation, ('group-end', 'body')),
default('#pop'),
],
'whitespace': [
('\s+', Text),
('%.*?$', Comment.SingleLine),
],
}
def setup(app):
add_entry_point('pygments.styles', 'pybtex', 'pybtex_doctools.pygments', 'PybtexStyle')
add_entry_point('pygments.lexers', 'bibtex-pybtex', 'pybtex_doctools.pygments', 'BibTeXLexer')
add_entry_point('pygments.lexers', 'bst-pybtex', 'pybtex_doctools.pygments', 'BSTLexer')
pybtex-0.21/docs/source/ 0000755 0001750 0001750 00000000000 13040475070 014525 5 ustar and and 0000000 0000000 pybtex-0.21/docs/source/cmdline.rst 0000644 0001750 0001750 00000011342 12614120531 016666 0 ustar and and 0000000 0000000 ======================
Command line interface
======================
.. contents::
:local:
Making bibliographies with :command:`pybtex`
============================================
The :command:`pybtex` executable is used in the same was as the original :command:`bibtex`
command and accepts the same command line options.
The only difference is that you type :command:`pybtex` instead of
:command:`bibtex`.
For example, to compile the bibliography for a LaTeX file named
:file:`book.tex`, you need to type:
.. code-block:: shell
$ latex book
$ pybtex book
$ latex book
$ latex book # to get cross-references right
See the `BibTeX tutorial`_ by Andrew Roberts for a basic explanation of how to use
BibTeX.
.. _BibTeX tutorial: http://www.andy-roberts.net/writing/latex/bibliographies
Bibliography formats other then BibTeX
--------------------------------------
.. todo::
link to BibTeX format description
Pybtex is fully compatible with BibTeX' :file:`.bib` files.
Besides that, Pybtex supports other bibliography formats.
The list of supported formats can bee seen in the output of :command:`pybtex --help`.
By default, the BibTeX format is used. If a LaTeX file :file:`book.tex` contains:
.. code-block:: latex
\bibliogrpahy{mybook}
Then this command:
.. code-block:: shell
$ pybtex book
will expect to find the bibliography data in a BibTeX-formatted file :file:`mybook.bib`.
Pybtex can be instructed to use a different format with the :option:`--format` option.
For example this command:
.. code-block:: shell
$ pybtex --format yaml book
will tell Pybtex to look for a YAML-formatted file :file:`mybook.yaml` instead of :file:`mybook.bib`).
Support for additional bibliography formats can be added by :doc:`plugins `.
Pythonic bibliography styles
----------------------------
BibTeX has a built-in stack oriented programming language for defining
bibliography formatting styles. This language is used in :file:`.bst`
style files. Pybtex is fully compatible with BIbTeX' :file:`.bst` style files.
Additionally, Pybtex allows
:doc:`to write bibliography styles in Python `.
Some base BibTeX styles, including ``plain``, ``alpha``, ``unsrt``, have been
already ported to Python. They can be found in
:source:`pybtex/style/formatting` subdirectory. Additional
styles can be added as :doc:`plugins `.
By default, Pybtex uses BibTeX' :file:`.bst` styles. You can switch the style
language from BibTeX to Python with the :option:`--style-language` option:
.. code-block:: shell
$ pybtex --style-language python book
One of the advantage of using Pythonic styles is that they can produce HTML,
Markdown or plain text output besides the usual LaTeX markup.
To change the output backend from LaTeX to something else,
use the :option:`--output-backend` option:
.. code-block:: shell
$ pybtex --style-language python --output-backend html book
$ pybtex --style-language python --output-backend plaintext book
(In this case Pybtex will write the bibliography to :file:`book.html` or
:file:`book.txt` instead of :file:`book.bbl`).
Support for other markup formats can be added by :doc:`plugins `.
Additionally, Pythonic styles are configurable with command line options to
some extent. For example, the :option:`--name-style` option tells Pybtex to
use a different name formatting style, :option:`--abbreviate-names` forces
Pybtex to use the abbreviated name format, etc. See :command:`pybtex --help`
for more options.
Converting bibliography databases with :command:`bibtex-convert`
================================================================
Pybtex comes with an additional utility called :command:`pybtex-convert`.
It converts bibliography databases between supported formats:
.. code-block:: shell
$ pybtex-convert book.bib book.yaml
Be aware that the conversion is not always lossless. For example:
- BibTeX' string macros are substituted by their values during conversion.
- BibTeXML does not support LaTeX preambles.
- In the standard BibTeX format, names are stored as single strings. BibTexML
and Pybtex' YAML format store first name, last name, and other name parts
seprately.
Pretty-printing bibliography databases with :command:`bibtex-format`
====================================================================
Sometimes you would want to convert a bibliography database to a
human-readable format. Pybtex has another utility called :command:`pybtex-format` for
that:
.. code-block:: shell
$ pybtex-format book.bib book.txt
$ pybtex-format book.bib book.html
By default, the ``unsrt`` style is used for formatting. This can be changed with the
:option:`--style` option:
.. code-block:: shell
$ pybtex-format --style alpha book.bib book.txt
pybtex-0.21/docs/source/history.rst 0000644 0001750 0001750 00000000114 12614120531 016747 0 ustar and and 0000000 0000000 ===============
Version history
===============
.. include:: ../../CHANGES
pybtex-0.21/docs/source/api/ 0000755 0001750 0001750 00000000000 13040475070 015276 5 ustar and and 0000000 0000000 pybtex-0.21/docs/source/api/parsing.rst 0000644 0001750 0001750 00000006016 12614120531 017471 0 ustar and and 0000000 0000000 =====================================
Reading and writing bibliography data
=====================================
.. testsetup:: *
from pybtex.database import BibliographyData, Entry, Person, parse_string
.. contents::
:local:
Reading bibliography data
=========================
One of the most common things to do with Pybtex API is parsing BibTeX files.
There are several high level functions in the :py:mod:`pybtex.database` module
for reading bibliography databases.
.. autofunction:: pybtex.database.parse_string
.. autofunction:: pybtex.database.parse_bytes
.. autofunction:: pybtex.database.parse_file
Each of these functions does basically the same thing.
It reads the bibliography data from a string or a file and returns a
:py:class:`.BibliographyData` object containing all the bibliography data.
Here is a quick example:
.. doctest::
>>> from pybtex.database import parse_file
>>> bib_data = parse_file('../examples/tugboat/tugboat.bib')
>>> print bib_data.entries['Knuth:TB8-1-14'].fields['title']
Mixing right-to-left texts with left-to-right texts
>>> for author in bib_data.entries['Knuth:TB8-1-14'].persons['author']:
... print(unicode(author))
Knuth, Donald
MacKay, Pierre
Writing bibliography data
=========================
The :py:class:`.BibliographyData` class has several methods that are
symmetrical to the functions described above:
- :py:meth:`.BibliographyData.to_string` formats the bibliograhy data into a string,
- :py:meth:`.BibliographyData.to_bytes` formats the bibliograhy data into a byte string,
- :py:meth:`.BibliographyData.to_file` writes the bibliograhy data to a file.
.. doctest::
>>> from pybtex.database import BibliographyData, Entry
>>> bib_data = BibliographyData({
... 'article-minimal': Entry('article', [
... ('author', 'L[eslie] B. Lamport'),
... ('title', 'The Gnats and Gnus Document Preparation System'),
... ('journal', "G-Animal's Journal"),
... ('year', '1986'),
... ]),
... })
>>> print bib_data.to_string('bibtex')
@article{article-minimal,
author = "L[eslie] B. Lamport",
title = "The Gnats and Gnus Document Preparation System",
journal = "G-Animal's Journal",
year = "1986"
}
Bibliography data classes
=========================
Pybtex uses several classes to represent bibligraphy databases:
- :py:class:`.BibliographyData` is a collection of individual bibliography
entries and some additional metadata.
- :py:class:`.Entry` is a single bibliography entry (a book, an article, etc.).
An entry has a key (like ``"knuth74"``), a type (``"book"``, ``"article"``, etc.),
and a number of key-value fields (``"author"``, ``"title"``, etc.).
- :py:class:`.Person` is a person related to a bibliography entry
(usually as an author or an editor).
.. autoclass:: pybtex.database.BibliographyData
:members:
.. autoclass:: pybtex.database.Entry
:members:
.. autoclass:: pybtex.database.Person
:members:
pybtex-0.21/docs/source/api/plugins.rst 0000644 0001750 0001750 00000005026 13040472400 017506 0 ustar and and 0000000 0000000 =============================
Extending Pybtex with plugins
=============================
.. contents::
:local:
Pybtex uses plugins for bibliography data formats, output markup formats and
bibliography formatting styles. This allows to add new formats or styles to
Pybtex withoud modifying Pybtex itself.
The plugins are based on `Setuptools' entry points `_.
Entry points
============
Here is the list of entry points supported by Pybtex.
pybtex.database.input
---------------------
This entry point is used for bibliography parsers.
Must point to a subclass of :py:class:`pybtex.database.input.BaseParser`.
There is also an additional entry point called ``pybtex.database.output.suffixes``.
It is used for registering bibliography formats for specific file suffixes
(like BibTeX for :file:`.bib` files).
For example, a JSON input plugin could use these entry points:
.. sourcecode:: ini
[pybtex.database.input]
json = pybtexjson:JSONParser
[pybtex.database.input.suffixes]
.json = pybtexjson:JSONParser
pybtex.database.output
----------------------
This entry poing is used for bibliography writers.
Must point to a subclass of :py:class:`pybtex.database.output.BaseWriter`.
There is also an additional entry point called ``pybtex.database.output.suffixes``.
It is used for registering default plugins for specific file suffixes in the
same way as ``pybtex.database.input.suffixes`` described above.
pybtex.backends
---------------
This entry point is for adding new output markup formats for Pythonic bibliography
styles. The built-in plugins are ``latex``, ``html``, ``markdown``, and ``plaintext``.
Must point to a :py:class:`pybtex.backends.BaseBackend` subclass.
pybtex.style.formatting
-----------------------
This is the entry point for Pythonic bibliography styles. Must point to a
:py:class:`pybtex.style.formatting.BaseStyle` subclass.
pybtex.style.labels
-------------------
Label styles for Pythonic bibliography styles.
pybtex.style.names
------------------
Name styles for Pythonic bibliography styles.
pybtex.style.sorting
--------------------
Sorting styles for Pythonic bibliography styles.
Registering plugins
===================
See `Setuptools' documentation`_.
.. _Setuptools' documentation: https://setuptools.readthedocs.io/en/latest/setuptools.html#extensible-applications-and-frameworks
Example plugins
===============
An example project directory with two simple plugins and a ``setup.py`` file can
be found in the :source:`examples/sample_plugins` subdirectory.
pybtex-0.21/docs/source/api/formatting.rst 0000644 0001750 0001750 00000021434 12614120531 020201 0 ustar and and 0000000 0000000 =========================
Formatting bibliographies
=========================
.. contents::
:local:
The main purpose of Pybtex is turning machine-readable bibliography data into
human-readable bibliographies formatted in a specific style.
Pybtex reads bibliography data that looks like this:
.. sourcecode:: bibtex
@book{graham1989concrete,
title = "Concrete mathematics: a foundation for computer science",
author = "Graham, Ronald Lewis and Knuth, Donald Ervin and Patashnik, Oren",
year = "1989",
publisher = "Addison-Wesley"
}
and formats it like this:
R. L. Graham, D. E. Knuth, and O. Patashnik.
*Concrete mathematics: a foundation for computer science*.
Addison-Wesley, 1989.
Pybtex contains two different formatting engines:
- The :ref:`BibTeX engine ` uses BibTeX ``.bst`` styles.
- The :ref:`Python engine ` uses styles written in Python.
.. _bibtex-engine:
BibTeX engine
=============
The BibTeX engine is fully compatible with BibTeX style files and is used by default.
How it works
------------
When you type :command:`pybtex mydocument`, the following things happen:
1. Pybtex reads the file :file:`mydocument.aux` in the current directory.
This file is normally created by LaTeX and contains all sorts of auxiliary information
collected during processing of the LaTeX document.
Pybtex is interested in these three pieces of information:
Bibliography style:
First, Pybtex searches the :file:`.aux` file for a ``\bibstyle``
command that specifies which formatting style will be used.
For example, ``\bibstyle{unsrt}`` instructs Pybtex to use formatting
style defined in the file :file:`unsrt.bst`.
Bibliography data:
Next, Pybtex expects to find at least one ``\bibdata`` command in the
:file:`.aux` file that tells where to look for the bibliography data.
For example, ``\bibdata{mydocument}`` means "use the bibliography data
from :file:`mydocument.bib`".
Citations:
Finally, Pybtex needs to know which entries to put into the resulting
bibliography. Pybtex gets the list of citation keys from
``\citation`` commands in the :file:`.aux` file.
For example, ``\citation{graham1989concrete}`` means "include the
entry with the key ``graham1989concrete`` into the resulting bibliograhy".
A wildcard citation ``\citation{*}`` tells Pybtex to format the
bibliography for all entries from all data files specified by
all ``\bibdata`` commands.
2. Pybtex executes the style program in the :file:`.bst` file specified by
the ``\bibstyle`` command in the :file:`.aux` file. As a result, a
:file:`.bbl` file containing the resulting formatted bibliography is
created.
A :file:`.bst` style file is a program in a domain-specific stack-based
language. A typical piece of the :file:`.bst` code looks like this:
.. code-block:: bst-pybtex
FUNCTION {format.bvolume}
{ volume empty$
{ "" }
{ "volume" volume tie.or.space.connect
series empty$
'skip$
{ " of " * series emphasize * }
if$
"volume and number" number either.or.check
}
if$
}
The code in a :file:`.bst` file contains the complete step-by-step
instructions on how to create the formatted bibliography from the given
bibliography data and citation keys. For example, a ``READ`` command
tells Pybtex to read the bibliography data from all files specified by
``\bibdata`` commands in the ``.aux`` file, an ``ITERATE`` command tells
Pybtex to execute a piece of code for each citation key specified by
``\citation`` commands, and so on. The built-in ``write$`` function tells
Pybtex to write the given string into the resulting :file:`.bbl` file.
Pybtex implements all these commands and built-in functions and simply
executes the :file:`.bst` program step by step.
A complete reference of the :file:`.bst` language can be found in the
`BibTeX hacking guide`_ by Oren Patashnik. It is available by running
:command:`texdoc btxhak` in most TeX distributions.
.. _`BibTeX hacking guide`: http://mirrors.ctan.org/biblio/bibtex/base/btxhak.pdf
.. _python-engine:
Python engine
=============
The Python engine is enabled by running :command:`pybtex` with the :option:`-l python` option.
Differences from the BibTeX engine
----------------------------------
* Formatting styles are written in Python instead of the :file:`.bst` language.
* Formatting styles are not tied to LaTeX and do not use hardcoded LaTeX
markup. Instead of that they produce format-agnostic :py:class:`pybtex.richtext.Text`
objects that can be converted to any markup format (LaTeX, Markdown, HTML, etc.).
* Name formatting, label formatting, and sorting styles are defined separately
from the main style.
How it works
------------
When you type :command:`pybtex -l python mydocument`, this things happen:
1. Pybtex reads the file :file:`mydocument.aux` in the current directory and
extracts the name of the the bibliography style, the list of bibliography
data files and the list of citation keys.
This step is exactly the same as with the BibTeX engine.
2. Pybtex reads the biliography data from all data files specified in the
:file:`.aux` file into a single :py:class:`.BibliographyData` object.
3. Then the formatting style is loaded. The formatting style is a
Python class with a :py:meth:`~.format_bibliography()` method. Pybtex passes the
bibliography data (a :py:class:`.BibliographyData` object) and the list of
citation keys to :py:meth:`~.format_bibliography()`.
4. The formatting style formats each of the requested bibliography entries
in a style-specific way.
When it comes to formatting names, a name formatting style is loaded and
used. A name formatting style is also a Python class with a specific
interface. Similarly, a label formatting style is used to format entry
labels, and a sorting style is used to sort the resulting style. Each
formatting style has a default name style, a default label style and a
default sorting style. The defaults can be overridden with options passed
to the main style class.
Each formatted entry is put into a :py:class:`.FormattedEntry` object
which is just a container for the formatted label, the formatted entry
text (a :py:class:`pybtex.richtext.Text` object) and the entry key. The reason
that the label, the key and the main text are stored separately is to give the
output backend more flexibility when converting the
:py:class:`.FormattedEntry` object to the actual markup. For example, the
HTML backend may want to format the bibliography as a definition list, the
LaTeX backend would use ``\bibitem[label]{key} text`` constructs, etc.
Formatted entries are put into a :py:class:`.FormattedBibliography`
object---it simply contains a list of :py:class:`.FormattedEntry` objects
and some additional metadata.
5. The resulting :py:class:`.FormattedBibliography` is passed to the output
backend. The default backend is LaTeX. It can be changed with the ``pybtex
--output-backend`` option. The output backend converts the formatted
bibliography to the specific markup format and writes it to the output
file.
Python API
==========
The base interface
------------------
Both the Python engine and the BibTeX engine use the same interface
defined in :py:class:`pybtex.Engine`.
:py:class:`pybtex.Engine` has a handful of methods but most of them are just
convenience wrappers for :py:meth:`.Engine.format_from_files` that does the
actual job.
.. autoclass:: pybtex.Engine
:members:
.. _bibtex-engine-api:
The BibTeXEngine class
----------------------
The BibTeX engine lives in the ``pybtex.bibtex`` module.
The public interface consists of the :py:class:`.BibTeXEngine` class and a
couple of convenience functions.
.. autoclass:: pybtex.bibtex.BibTeXEngine
:members:
.. autofunction:: pybtex.bibtex.make_bibliography
.. autofunction:: pybtex.bibtex.format_from_string
.. autofunction:: pybtex.bibtex.format_from_strings
.. autofunction:: pybtex.bibtex.format_from_file
.. autofunction:: pybtex.bibtex.format_from_files
The PybtexEngine class
----------------------
The Python engine resides in the ``pybtex`` module
and uses an interface similar to the :ref:`BibTeX engine `.
There is the :py:class:`.PybtexEngine` class and some convenience functions.
.. autoclass:: pybtex.PybtexEngine
:members:
.. autofunction:: pybtex.make_bibliography
.. autofunction:: pybtex.format_from_string
.. autofunction:: pybtex.format_from_strings
.. autofunction:: pybtex.format_from_file
.. autofunction:: pybtex.format_from_files
pybtex-0.21/docs/source/api/index.rst 0000644 0001750 0001750 00000000164 12614120531 017133 0 ustar and and 0000000 0000000 ==========
Python API
==========
.. toctree::
:maxdepth: 2
parsing
formatting
styles
plugins
pybtex-0.21/docs/source/api/styles.rst 0000644 0001750 0001750 00000013776 13040472400 017363 0 ustar and and 0000000 0000000 ================
Designing styles
================
.. testsetup:: *
from pybtex.richtext import Text, String, Tag, HRef, Protected, Symbol, nbsp, textutils
.. currentmodule:: pybtex.richtext
.. contents::
:local:
.. _rich-text:
Rich text
=========
Pybtex has a set of classes for working with formatted text
and producing formatted output.
A piece of formatted text in Pybtex is represented by a :py:class:`Text`
object.
A :py:class:`Text` is basically a container that holds a list of
* plain text parts, represented by :py:class:`String` objects,
* formatted parts, represented by :py:class:`Tag` and :py:class:`HRef` objects.
The basic workflow is:
1. Construct a :py:class:`Text` object.
2. Render it as LaTeX, HTML or other markup.
.. doctest::
>>> from pybtex.richtext import Text, Tag
>>> text = Text('How to be ', Tag('em', 'a cat'), '.')
>>> print text.render_as('html')
How to be a cat.
>>> print text.render_as('latex')
How to be \emph{a cat}.
Rich text classes
-----------------
There are several rich text classes in Pybtex:
- :py:class:`Text`
- :py:class:`String`
- :py:class:`Tag`
- :py:class:`HRef`
- :py:class:`Protected`
:py:class:`Text` is the top level container that may contain
:py:class:`String`, :py:class:`Tag`, and :py:class:`HRef` objects.
When a :py:class:`Text` object is rendered into markup,
it renders all of its child objects, then concatenates the result.
:py:class:`String` is just a wrapper for a single Python string.
:py:class:`Tag` and :py:class:`HRef` are also containers that may contain
other :py:class:`String`, :py:class:`Tag`, and :py:class:`HRef` objects. This
makes nested formatting possible. For example, this stupidly formatted text:
|CTAN hyperlink|_ is *comprehensive*.
.. |CTAN hyperlink| replace:: *Comprehensive* TeX Archive Network
.. _CTAN hyperlink: http://ctan.org/
is represented by this object tree:
.. doctest::
>>> text = Text(
... HRef('http://ctan.org/', Tag('em', 'Comprehensive'), ' TeX Archive Network'),
... ' is ',
... Tag('em', 'comprehensive'),
... '.',
... )
>>> print text.render_as('html')
Comprehensive TeX Archive Network is comprehensive.
:py:class:`Protected` represents a "protected" piece of text, something like
{braced text} in BibTeX. It is not affected by case-changing operations, like
:py:meth:`Text.upper()` or :py:meth:`Text.lower()`, and is not splittable by
:py:meth:`Text.split()`.
All rich text classes share the same API which is more or less similar to plain
`Python strings`_.
.. _Python strings: https://docs.python.org/3/library/stdtypes.html#string-methods
Like Python strings, rich text objects are supposed to be immutable. Methods like
:py:meth:`Text.append` or :py:meth:`Text.upper` return a new :py:class:`Text`
object instead of modifying the data in place.
Attempting to modify the contents of an existing :py:class:`Text` object is
not supported and may lead to weird results.
Here we document the methods of the :py:class:`Text` class.
The other classes have the same methods.
.. autoclass:: pybtex.richtext.Text
:members:
:inherited-members:
.. automethod:: Text.__init__
.. automethod:: Text.__eq__
.. automethod:: Text.__len__
.. automethod:: Text.__contains__
.. automethod:: Text.__getitem__
.. automethod:: Text.__add__
.. autoclass:: pybtex.richtext.String
.. autoclass:: pybtex.richtext.Tag
.. autoclass:: pybtex.richtext.HRef
.. autoclass:: pybtex.richtext.Protected
.. autoclass:: pybtex.richtext.Symbol
Style API
=========
A formatting style in Pybtex is a class inherited from
:py:class:`pybtex.style.formatting.BaseStyle`.
.. autoclass:: pybtex.style.formatting.BaseStyle
:members:
.. currentmodule:: pybtex.richtext
Pybtex loads the style class as a :doc:`plugin `,
instantiates it with proper parameters and
calls the :py:meth:`~.BaseStyle.format_bibliography` method that does
the actual formatting job.
The default implementation of :py:meth:`~.BaseStyle.format_bibliography`
calls a ``format_()`` method for each bibliography entry, where ````
is the entry type, in lowercase. For example, to format
an entry of type ``book``, the ``format_book()`` method is called.
The method must return a :py:class:`.Text` object.
Style classes are supposed to implement ``format_()`` methods
for all entry types they support. If a formatting method
is not found for some entry, Pybtex complains about unsupported entry type.
An example minimalistic style:
.. sourcecode:: python
from pybtex.style.formatting import BaseStyle
from pybtex.richtext import Text, Tag
class MyStyle(BaseStyle):
def format_article(self, entry):
return Text('Article ', Tag('em', entry.fields['title']))
Template language
=================
Manually creating :py:class:`.Text` objects may be tedious.
Pybtex has a small template language to simplify common formatting tasks,
like joining words with spaces, adding commas and periods, or handling missing fields.
The template language is is not very documented for now, so you should look at
the code in the :source:`pybtex.style.template ` module
and the :source:`existing styles `.
An example formatting style using template language:
.. sourcecode:: python
from pybtex.style.formatting import BaseStyle, toplevel
from pybtex.style.template import field, join, optional
class MyStyle(BaseStyle):
def format_article(self, entry):
if entry.fields['volume']:
volume_and_pages = join [field('volume'), optional [':', pages]]
else:
volume_and_pages = words ['pages', optional [pages]]
template = toplevel [
self.format_names('author'),
sentence [field('title')],
sentence [
tag('emph') [field('journal')], volume_and_pages, date],
]
return template.format_data(entry)
pybtex-0.21/docs/source/conf.py 0000644 0001750 0001750 00000021372 13040472400 016023 0 ustar and and 0000000 0000000 # -*- coding: utf-8 -*-
#
# Pybtex documentation build configuration file, created by
# sphinx-quickstart on Thu Jul 10 21:45:13 2014.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
from datetime import datetime
from pybtex import __version__
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.ifconfig',
# 'sphinx.ext.intersphinx',
'sphinx.ext.extlinks',
'pybtex_doctools.pygments',
]
# intersphinx_mapping = {
# 'python': ('https://docs.python.org/3/', None),
# }
extlinks = {
'source': ('https://bitbucket.org/pybtex-devs/pybtex/src/HEAD/%s', ''),
}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u"Pybtex User’s Guide"
copyright = u'2017, Andrey Golovizin'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = __version__
# The full version, including alpha/beta/rc tags.
release = version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
# pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'theme'
html_theme_path = ['..']
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
html_title = u"Pybtex User’s Guide"
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = 'Docs'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
html_context = {
'site_url': 'https://pybtex.org/',
}
# Output file base name for HTML help builder.
htmlhelp_basename = 'Pybtexdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'Pybtex.tex', u'Pybtex Documentation',
u'Andrey Golovizin', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'pybtex', u'Pybtex Documentation',
[u'Andrey Golovizin'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Pybtex', u'Pybtex Documentation',
u'Andrey Golovizin', 'Pybtex', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
stexinfo_no_detailmenu = False
rst_epilog = """
.. |download_url| replace:: Pybtex {release}
.. _download_url: https://pypi.python.org/packages/source/p/pybtex/pybtex-{release}.tar.bz2
""".format(release=release)
autodoc_member_order = 'bysource'
pybtex-0.21/docs/source/formats.rst 0000644 0001750 0001750 00000006027 13040472400 016731 0 ustar and and 0000000 0000000 =================
Supported formats
=================
.. contents::
:local:
Bibliography formats
====================
BibTeX
------
BibTeX is the default bibliography format used by Pybtex:
.. sourcecode:: bibtex-pybtex
@BOOK{strunk-and-white,
author = "Strunk, Jr., William and E. B. White",
title = "The Elements of Style",
publisher = "Macmillan",
edition = "Third",
year = 1979
}
Some links:
- `A basic description of the BibTeX format. `_
- `An in-depth description of the quirky BibTeX syntax. `_
BibTeXML
--------
`BibTeXML`_ is an attempt to translate
the BibTeX format into XML.
The above BibTeX snippet translates into this XML:
.. sourcecode:: xml
WilliamStrunkJr.E.B.
WhiteThe Elements of StyleMacmillanThird1979
YAML
----
We added our own experimental YAML-based bibliography format to Pybtex.
It is mostly a straightforward translation of `BibTeXML`_
into YAML:
.. sourcecode:: yaml
strunk-and-white:
type: book
author:
- first: William
last: Strunk
lineage: Jr.
- first: E.
middle: B.
last: White
title: The Elements of Style
publisher: Macmillan
edition: Third
year: 1979
.. _BibTeXML: http://bibtexml.sourceforge.net
Bibliography style formats
==========================
Pybtex currently supports bibliography styles in two formats:
- BibTeX' ``.bst`` files
- Pybtex' :doc:`Pythonic styles `
Output formats
==============
BibTeX's :file:`.bst` styles usually contain hardcoded LaTeX markup
and are LaTeX-only. Pythonic styles in Pybtex are markup-independent
and can output multiple formats, including:
- LaTeX
- Markdown
- HTML
- plain text
There is also `pybtex-docutils`_ by Matthias Troffaes that integrates Pybtex with Docutils_,
and `sphinxcontrib-bibtex`_ by the same author, integrating Pybtex with Sphinx_.
.. _pybtex-docutils: https://github.com/mcmtroffaes/pybtex-docutils
.. _sphinxcontrib-bibtex: https://github.com/mcmtroffaes/sphinxcontrib-bibtex
.. _Docutils: http://docutils.sourceforge.net/
.. _Sphinx: http://sphinx-doc.org/
pybtex-0.21/docs/source/index.rst 0000644 0001750 0001750 00000000256 12614120531 016364 0 ustar and and 0000000 0000000 ===================
Pybtex User's Guide
===================
.. toctree::
:maxdepth: 2
cmdline
formats
api/index
.. toctree::
:maxdepth: 1
history
pybtex-0.21/docs/generate_manpages.py 0000755 0001750 0001750 00000000250 13040464037 017245 0 ustar and and 0000000 0000000 #!/usr/bin/env python
from os import path
from pybtex_doctools.man import generate_manpages
if __name__ == '__main__':
generate_manpages(path.dirname(__file__))
pybtex-0.21/docs/theme/ 0000755 0001750 0001750 00000000000 13040475070 014327 5 ustar and and 0000000 0000000 pybtex-0.21/docs/theme/theme.conf 0000644 0001750 0001750 00000000144 12613214533 016277 0 ustar and and 0000000 0000000 [theme]
inherit = basic
stylesheet = master.css
pygments_style = pybtex
[options]
nosidebar = true
pybtex-0.21/docs/theme/static/ 0000755 0001750 0001750 00000000000 13040475070 015616 5 ustar and and 0000000 0000000 pybtex-0.21/docs/theme/static/master.css 0000644 0001750 0001750 00000007065 12614121472 017633 0 ustar and and 0000000 0000000 @media only screen {
.content {
margin-left: auto;
margin-right: auto;
padding: 0px 0px;
width: 100%;
max-width: 45em;
padding: 0.5em;
}
}
@media only screen and (max-width: 400px) {
body { font-size: 0.8em; }
}
body {
font-family: sans-serif;
background-color: white;
}
a {
color: #884400;
}
a:hover {
color: #BB8811;
}
p, dd, li {
font-family: serif;
line-height: 140%;
}
p {
margin-top: 1em;
margin-bottom: 1em;
-webkit-hyphens: auto;
-moz-hyphens: auto;
hyphens: auto;
}
li {
margin: 0.8ex 0 0.8ex 0;
}
img {
border: none;
}
h1, h2, h3, h1 a, h2 a, h3 a {
margin-top: 3ex;
margin-bottom: 1ex;
font-weight: bold;
color: #BB8811;
text-decoration: none;
}
h1 {
font-size: 2.4em;
}
h2 {
font-size: 1.6em;
}
h3 {
font-size: 1em;
}
a.headerlink {
visibility: hidden;
text-decoration: none;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
color: #884400;
}
.contents, .toctree-wrapper {
margin-left: 1em;
margin-bottom: 3ex;
}
.contents a, .toctree-wrapper a {
font-family: sans-serif;
}
.contents .topic-title {
display: none;
}
div.topic {
border: none !important;
padding: 0 !important;
}
dl.docutils dt {
margin-bottom: 0.5ex;
font-family: sans-serif;
}
dl.docutils dd {
margin: 0px 0px 0px 2em;
padding: 0px;
}
dl, dt {
font-size: 1em;
margin-top: 1em;
margin-bottom: 1em;
}
code, pre, tt {
font-size: 1em;
line-height: 140%;
font-family: monospace;
-webkit-hyphens: none;
-moz-hyphens: none;
hyphens: none;
}
code {
white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;
}
code.descname {
color: #884400;
font-weight: bold;
font-size: 120%;
}
dl.class > dt > .property {
font-weight: bold;
}
.literal {
background-color: #F0F0F0;
padding: 0.16em;
}
a .docutils.literal {
background: none;
}
.versionmodified {
font-style: italic;
}
.sourcecode, .highlight {
margin: 1em 0 1em 0;
}
.sourcecode pre, .highlight pre {
border: 0.08em solid #E0E0E0;
border-radius: 0.15em;
padding: 1em;
margin: 0;
}
th {
text-align: left;
}
.field-name {
margin: 0px;
padding: 0px 0.3em 0px 0px;
}
.field-body {
margin: 0px;
padding: 0px;
}
.field-list ul {
margin: 0px 0px 0px 0.5em;
padding-left: 1em;
}
.field-list li {
margin: 0;
}
.first {
margin-top: 0 !important;
}
.left {
float: left;
}
.right {
float: right;
}
.middle {
display: inline-block;
text-align: center;
}
.relbar {
margin: 1em 1em 3em 1em;
font-size: 0.85em;
}
.search input {
border: 1pt solid #aaa;
border-radius: 0.15em;
font-size: 0.85em;
padding: 0.62ex;
}
.prev-next {
margin-top: 3ex;
clear: both;
text-align: center;
word-wrap: normal;
}
.footer {
margin-top: 7em;
font-size: 80%;
opacity: 0.5;
clear: both;
text-align: center;
}
.admonition {
border: 0.4ex solid;
margin-top: 1ex !important;
margin-bottom: 1ex !important;
}
.admonition p {
margin: 1ex 1em;
padding: 0;
}
.warning {
border-color: #D04040;
}
.highlighted {
background-color: #fbe54e;
}
pybtex-0.21/docs/theme/static/print.css 0000644 0001750 0001750 00000000131 12613214533 017457 0 ustar and and 0000000 0000000 @import url(master.css);
a {
text-decoration: none;
}
div#buttons {
display: none;
}
pybtex-0.21/docs/theme/static/site.css 0000644 0001750 0001750 00000000575 12614120167 017303 0 ustar and and 0000000 0000000 @import url(master.css);
h1 {
font-size: 800%;
margin-top: 0.3ex;
margin-bottom: 0.2ex;
border-bottom-style: solid;
border-bottom-color: #884400;
border-bottom-width: 0.08em;
padding-bottom: 0.2ex;
}
p {
text-align: left;
}
.content {
margin-bottom: 2em;
}
.download-links {
margin-bottom: 3ex;
width: 100%;
text-align: right;
}
pybtex-0.21/docs/theme/layout.html 0000644 0001750 0001750 00000013455 13040472400 016534 0 ustar and and 0000000 0000000 {%- block doctype -%}
{%- endblock %}
{%- set url_root = pathto('', 1) %}
{# XXX necessary? #}
{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
{%- if not embedded and pagename != master_doc and docstitle %}
{%- set titlesuffix = " — "|safe + docstitle|e %}
{%- else %}
{%- set titlesuffix = "" %}
{%- endif %}
{%- macro toc() %}
Table of contents
{%- endmacro %}
{%- macro relbar() %}
Pybtex /
{%- if pagename != master_doc %}
{{ shorttitle|e }} /
{%- for parent in parents %}
{{ parent.title }} /
{%- endfor %}
{{ title }}
{%- else %}
{{ shorttitle|e }}
{%- endif %}