1PYBTEX(1) Pybtex User’s Guide PYBTEX(1)
2
6 pybtex - Pybtex Documentation
7
9 · Making bibliographies with pybtex
10 · Bibliography formats other then BibTeX
12 · Pythonic bibliography styles
14 · Converting bibliography databases with bibtex-convert
16 · Pretty-printing bibliography databases with bibtex-format
18 Making bibliographies with pybtex
20 The pybtex executable is used in the same was as the original bibtex
21 command and accepts the same command line options. The only difference
22 is that you type pybtex instead of bibtex.
23 For example, to compile the bibliography for a LaTeX file named
25 book.tex, you need to type:
26 $ latex book
28 $ pybtex book
29 $ latex book
30 $ latex book # to get cross-references right
31 See the BibTeX tutorial by Andrew Roberts for a basic explanation of
33 how to use BibTeX.
34 Bibliography formats other then BibTeX
36 Pybtex is fully compatible with BibTeX’ .bib files. Besides that, Pyb‐
37 tex supports other bibliography formats. The list of supported formats
38 can bee seen in the output of pybtex --help.
39 By default, the BibTeX format is used. If a LaTeX file book.tex con‐
41 tains:
42 \bibliogrpahy{mybook}
44 Then this command:
46 $ pybtex book
48 will expect to find the bibliography data in a BibTeX-formatted file
50 mybook.bib.
51 Pybtex can be instructed to use a different format with the --format
53 option. For example this command:
54 $ pybtex --format yaml book
56 will tell Pybtex to look for a YAML-formatted file mybook.yaml instead
58 of mybook.bib).
59 Support for additional bibliography formats can be added by plugins.
61 Pythonic bibliography styles
63 BibTeX has a built-in stack oriented programming language for defining
64 bibliography formatting styles. This language is used in .bst style
65 files. Pybtex is fully compatible with BIbTeX’ .bst style files.
66 Additionally, Pybtex allows to write bibliography styles in Python.
68 Some base BibTeX styles, including plain, alpha, unsrt, have been
69 already ported to Python. They can be found in pybtex/style/formatting
70 subdirectory. Additional styles can be added as plugins.
71 By default, Pybtex uses BibTeX’ .bst styles. You can switch the style
73 language from BibTeX to Python with the --style-language option:
74 $ pybtex --style-language python book
76 One of the advantage of using Pythonic styles is that they can produce
78 HTML, Markdown or plain text output besides the usual LaTeX markup. To
79 change the output backend from LaTeX to something else, use the --out‐
80 put-backend option:
81 $ pybtex --style-language python --output-backend html book
83 $ pybtex --style-language python --output-backend plaintext book
84 (In this case Pybtex will write the bibliography to book.html or
86 book.txt instead of book.bbl).
87 Support for other markup formats can be added by plugins.
89 Additionally, Pythonic styles are configurable with command line
91 options to some extent. For example, the --name-style option tells Pyb‐
92 tex to use a different name formatting style, --abbreviate-names forces
93 Pybtex to use the abbreviated name format, etc. See pybtex --help for
94 more options.
95 Converting bibliography databases with bibtex-convert
97 Pybtex comes with an additional utility called pybtex-convert. It con‐
98 verts bibliography databases between supported formats:
99 $ pybtex-convert book.bib book.yaml
101 Be aware that the conversion is not always lossless. For example:
103 · BibTeX’ string macros are substituted by their values during conver‐
105 sion.
106 · BibTeXML does not support LaTeX preambles.
108 · In the standard BibTeX format, names are stored as single strings.
110 BibTexML and Pybtex’ YAML format store first name, last name, and
111 other name parts seprately.
112 Pretty-printing bibliography databases with bibtex-format
114 Sometimes you would want to convert a bibliography database to a
115 human-readable format. Pybtex has another utility called pybtex-format
116 for that:
117 $ pybtex-format book.bib book.txt
119 $ pybtex-format book.bib book.html
120 By default, the unsrt style is used for formatting. This can be changed
122 with the --style option:
123 $ pybtex-format --style alpha book.bib book.txt
125
127 · Bibliography formats
128 · BibTeX
130 · BibTeXML
132 · YAML
134 · Bibliography style formats
136 · Output formats
138 Bibliography formats
140 BibTeX
141 BibTeX is the default bibliography format used by Pybtex:
142 @BOOK{strunk-and-white,
144 author = "Strunk, Jr., William and E. B. White",
145 title = "The Elements of Style",
146 publisher = "Macmillan",
147 edition = "Third",
148 year = 1979
149 }
150 Some links:
152 · A basic description of the BibTeX format.
154 · An in-depth description of the quirky BibTeX syntax.
156 BibTeXML
158 BibTeXML is an attempt to translate the BibTeX format into XML. The
159 above BibTeX snippet translates into this XML:
160 <bibtex:entry id="strunk-and-white">
162 <bibtex:book>
163 <bibtex:author>
164 <bibtex:person>
165 <bibtex:first>William</bibtex:first>
166 <bibtex:last>Strunk</bibtex:last>
167 <bibtex:lineage>Jr.</bibtex:lineage>
168 </bibtex:person>
169 <bibtex:person>
170 <bibtex:first>E.</bibtex:first>
171 <bibtex:middle>B.</bibtex:first>
172 <bibtex:last>White</bibtex:last>
173 </bibtex:person>
174 </bibtex:author>
175 <bibtex:title>The Elements of Style</bibtex:title>
176 <bibtex:publisher>Macmillan<bibtex:publisher>
177 <bibtex:edition>Third</bibtex:edition>
178 <bibtex:year>1979</bibtex:year>
179 </bibtex:book>
180 </bibtex:entry>
181 YAML
183 We added our own experimental YAML-based bibliography format to Pybtex.
184 It is mostly a straightforward translation of BibTeXML into YAML:
185 strunk-and-white:
187 type: book
188 author:
189 - first: William
190 last: Strunk
191 lineage: Jr.
192 - first: E.
193 middle: B.
194 last: White
195 title: The Elements of Style
196 publisher: Macmillan
197 edition: Third
198 year: 1979
199 Bibliography style formats
201 Pybtex currently supports bibliography styles in two formats:
202 · BibTeX’ .bst files
204 · Pybtex’ Pythonic styles
206 Output formats
208 BibTeX’s .bst styles usually contain hardcoded LaTeX markup and are
209 LaTeX-only. Pythonic styles in Pybtex are markup-independent and can
210 output multiple formats, including:
211 · LaTeX
213 · Markdown
215 · HTML
217 · plain text
219 There is also pybtex-docutils by Matthias Troffaes that integrates Pyb‐
221 tex with Docutils, and sphinxcontrib-bibtex by the same author, inte‐
222 grating Pybtex with Sphinx.
223
225 Reading and writing bibliography data
226 · Reading bibliography data
227 · Writing bibliography data
229 · Bibliography data classes
231 Reading bibliography data
233 One of the most common things to do with Pybtex API is parsing BibTeX
234 files. There are several high level functions in the pybtex.database
235 module for reading bibliography databases.
236 pybtex.database.parse_string(value, bib_format, **kwargs)
238 Parse a Unicode string containing bibliography data and return a
239 BibliographyData object.
240 Parameters
242 · value – Unicode string.
244 · bib_format – Data format (“bibtex”, “yaml”, etc.).
246 New in version 0.19.
248 pybtex.database.parse_bytes(value, bib_format, **kwargs)
251 Parse a byte string containing bibliography data and return a
252 BibliographyData object.
253 Parameters
255 · value – Byte string.
257 · bib_format – Data format (for example, “bibtexml”).
259 New in version 0.19.
261 pybtex.database.parse_file(file, bib_format=None, **kwargs)
264 Read bibliography data from file and return a BibliographyData
265 object.
266 Parameters
268 · file – A file name or a file-like object.
270 · bib_format – Data format (“bibtex”, “yaml”, etc.). If
272 not specified, Pybtex will try to guess by the file
273 name.
274 New in version 0.19.
276 Each of these functions does basically the same thing. It reads the
279 bibliography data from a string or a file and returns a
280 BibliographyData object containing all the bibliography data.
281 Here is a quick example:
283 >>> from pybtex.database import parse_file
285 >>> bib_data = parse_file('../examples/tugboat/tugboat.bib')
286 >>> print(bib_data.entries['Knuth:TB8-1-14'].fields['title'])
287 Mixing right-to-left texts with left-to-right texts
288 >>> for author in bib_data.entries['Knuth:TB8-1-14'].persons['author']:
289 ... print(unicode(author))
290 Knuth, Donald
291 MacKay, Pierre
292 Writing bibliography data
294 The BibliographyData class has several methods that are symmetrical to
295 the functions described above:
296 · BibliographyData.to_string() formats the bibliograhy data into a
298 string,
299 · BibliographyData.to_bytes() formats the bibliograhy data into a byte
301 string,
302 · BibliographyData.to_file() writes the bibliograhy data to a file.
304 >>> from pybtex.database import BibliographyData, Entry
306 >>> bib_data = BibliographyData({
307 ... 'article-minimal': Entry('article', [
308 ... ('author', 'L[eslie] B. Lamport'),
309 ... ('title', 'The Gnats and Gnus Document Preparation System'),
310 ... ('journal', "G-Animal's Journal"),
311 ... ('year', '1986'),
312 ... ]),
313 ... })
314 >>> print(bib_data.to_string('bibtex'))
315 @article{article-minimal,
316 author = "L[eslie] B. Lamport",
317 title = "The Gnats and Gnus Document Preparation System",
318 journal = "G-Animal's Journal",
319 year = "1986"
320 }
321 Bibliography data classes
324 Pybtex uses several classes to represent bibligraphy databases:
325 · BibliographyData is a collection of individual bibliography entries
327 and some additional metadata.
328 · Entry is a single bibliography entry (a book, an article, etc.).
330 An entry has a key (like "knuth74"), a type ("book", "article",
332 etc.), and a number of key-value fields ("author", "title", etc.).
333 · Person is a person related to a bibliography entry (usually as an
335 author or an editor).
336 class pybtex.database.BibliographyData(entries=None, preamble=None,
338 wanted_entries=None, min_crossrefs=2)
339 entries = None
341 A dictionary of bibliography entries referenced by their
342 keys.
343 The dictionary is case insensitive:
345 >>> bib_data = parse_string("""
347 ... @ARTICLE{gnats,
348 ... author = {L[eslie] A. Aamport},
349 ... title = {The Gnats and Gnus Document Preparation System},
350 ... }
351 ... """, 'bibtex')
352 >>> bib_data.entries['gnats'] == bib_data.entries['GNATS']
353 True
354 property preamble
356 LaTeX preamble.
357 >>> bib_data = parse_string(r"""
359 ... @PREAMBLE{"\newcommand{\noopsort}[1]{}"}
360 ... """, 'bibtex')
361 >>> print(bib_data.preamble)
362 \newcommand{\noopsort}[1]{}
363 New in version 0.19: Earlier versions used
365 get_preamble(), which is now deprecated.
366 get_preamble()
369 Deprecated since version 0.19: Use preamble instead.
370 to_string(bib_format, **kwargs)
373 Return the data as a unicode string in the given format.
374 Parameters
376 bib_format – Data format (“bibtex”, “yaml”, etc.).
377 New in version 0.19.
379 to_bytes(bib_format, **kwargs)
382 Return the data as a byte string in the given format.
383 Parameters
385 bib_format – Data format (“bibtex”, “yaml”, etc.).
386 New in version 0.19.
388 to_file(file, bib_format=None, **kwargs)
391 Save the data to a file.
392 Parameters
394 · file – A file name or a file-like object.
396 · bib_format – Data format (“bibtex”, “yaml”,
398 etc.). If not specified, Pybtex will try to
399 guess by the file name.
400 New in version 0.19.
402 lower()
405 Return another BibliographyData with all identifiers con‐
406 verted to lowercase.
407 >>> data = parse_string("""
409 ... @BOOK{Obrazy,
410 ... title = "Obrazy z Rus",
411 ... author = "Karel Havlíček Borovský",
412 ... }
413 ... @BOOK{Elegie,
414 ... title = "Tirolské elegie",
415 ... author = "Karel Havlíček Borovský",
416 ... }
417 ... """, 'bibtex')
418 >>> data_lower = data.lower()
419 >>> list(data_lower.entries.keys())
420 ['obrazy', 'elegie']
421 >>> for entry in data_lower.entries.values():
422 ... entry.key
423 ... list(entry.persons.keys())
424 ... list(entry.fields.keys())
425 'obrazy'
426 ['author']
427 ['title']
428 'elegie'
429 ['author']
430 ['title']
431 class pybtex.database.Entry(type_, fields=None, persons=None)
433 A bibliography entry.
434 key = None
436 Entry key (for example, 'fukushima1980neocognitron').
437 type = None
439 Entry type ('book', 'article', etc.).
440 fields = None
442 A dictionary of entry fields. The dictionary is ordered
443 and case-insensitive.
444 persons = None
446 A dictionary of entry persons, by their roles.
447 The most often used roles are 'author' and 'editor'.
449 class pybtex.database.Person(string='', first='', middle='',
451 prelast='', last='', lineage='')
452 A person or some other person-like entity.
453 >>> knuth = Person('Donald E. Knuth')
455 >>> knuth.first_names
456 ['Donald']
457 >>> knuth.middle_names
458 ['E.']
459 >>> knuth.last_names
460 ['Knuth']
461 first_names = None
463 A list of first names.
464 New in version 0.19: Earlier versions used first(), which
466 is now deprecated.
467 middle_names = None
470 A list of middle names.
471 New in version 0.19: Earlier versions used middle(),
473 which is now deprecated.
474 prelast_names = None
477 A list of pre-last (aka von) name parts.
478 New in version 0.19: Earlier versions used middle(),
480 which is now deprecated.
481 last_names = None
484 A list of last names.
485 New in version 0.19: Earlier versions used last(), which
487 is now deprecated.
488 lineage_names = None
491 A list of linage (aka Jr) name parts.
492 New in version 0.19: Earlier versions used lineage(),
494 which is now deprecated.
495 property bibtex_first_names
498 A list of first and middle names together. (BibTeX
499 treats all middle names as first.)
500 New in version 0.19: Earlier versions used
502 Person.bibtex_first(), which is now deprecated.
503 >>> knuth = Person('Donald E. Knuth')
506 >>> knuth.bibtex_first_names
507 ['Donald', 'E.']
508 get_part(type, abbr=False)
510 Get a list of name parts by type.
511 >>> knuth = Person('Donald E. Knuth')
513 >>> knuth.get_part('first')
514 ['Donald']
515 >>> knuth.get_part('last')
516 ['Knuth']
517 property rich_first_names
519 A list of first names converted to rich text.
520 New in version 0.20.
522 property rich_middle_names
525 A list of middle names converted to rich text.
526 New in version 0.20.
528 property rich_prelast_names
531 A list of pre-last (aka von) name parts converted to rich
532 text.
533 New in version 0.20.
535 property rich_last_names
538 A list of last names converted to rich text.
539 New in version 0.20.
541 property rich_lineage_names
544 A list of lineage (aka Jr) name parts converted to rich
545 text.
546 New in version 0.20.
548 first(abbr=False)
551 Deprecated since version 0.19: Use first_names instead.
552 middle(abbr=False)
555 Deprecated since version 0.19: Use middle_names instead.
556 prelast(abbr=False)
559 Deprecated since version 0.19: Use prelast_names instead.
560 last(abbr=False)
563 Deprecated since version 0.19: Use last_names instead.
564 lineage(abbr=False)
567 Deprecated since version 0.19: Use lineage_names instead.
568 bibtex_first()
571 Deprecated since version 0.19: Use bibtex_first_names
572 instead.
573 Formatting bibliographies
576 · BibTeX engine
577 · How it works
579 · Python engine
581 · Differences from the BibTeX engine
583 · How it works
585 · Python API
587 · The base interface
589 · The BibTeXEngine class
591 · The PybtexEngine class
593 The main purpose of Pybtex is turning machine-readable bibliography
595 data into human-readable bibliographies formatted in a specific style.
596 Pybtex reads bibliography data that looks like this:
597 @book{graham1989concrete,
599 title = "Concrete mathematics: a foundation for computer science",
600 author = "Graham, Ronald Lewis and Knuth, Donald Ervin and Patashnik, Oren",
601 year = "1989",
602 publisher = "Addison-Wesley"
603 }
604 and formats it like this:
606 R. L. Graham, D. E. Knuth, and O. Patashnik. Concrete mathematics:
607 a foundation for computer science. Addison-Wesley, 1989.
608 Pybtex contains two different formatting engines:
610 · The BibTeX engine uses BibTeX .bst styles.
612 · The Python engine uses styles written in Python.
614 BibTeX engine
616 The BibTeX engine is fully compatible with BibTeX style files and is
617 used by default.
618 How it works
620 When you type pybtex mydocument, the following things happen:
621 1. Pybtex reads the file mydocument.aux in the current directory. This
623 file is normally created by LaTeX and contains all sorts of auxil‐
624 iary information collected during processing of the LaTeX document.
625 Pybtex is interested in these three pieces of information:
627 Bibliography style:
629 First, Pybtex searches the .aux file for a \bibstyle command
630 that specifies which formatting style will be used.
631 For example, \bibstyle{unsrt} instructs Pybtex to use format‐
633 ting style defined in the file unsrt.bst.
634 Bibliography data:
636 Next, Pybtex expects to find at least one \bibdata command in
637 the .aux file that tells where to look for the bibliography
638 data.
639 For example, \bibdata{mydocument} means “use the bibliography
641 data from mydocument.bib”.
642 Citations:
644 Finally, Pybtex needs to know which entries to put into the
645 resulting bibliography. Pybtex gets the list of citation
646 keys from \citation commands in the .aux file.
647 For example, \citation{graham1989concrete} means “include the
649 entry with the key graham1989concrete into the resulting bib‐
650 liograhy”.
651 A wildcard citation \citation{*} tells Pybtex to format the
653 bibliography for all entries from all data files specified by
654 all \bibdata commands.
655 2. Pybtex executes the style program in the .bst file specified by the
657 \bibstyle command in the .aux file. As a result, a .bbl file con‐
658 taining the resulting formatted bibliography is created.
659 A .bst style file is a program in a domain-specific stack-based lan‐
661 guage. A typical piece of the .bst code looks like this:
662 FUNCTION {format.bvolume}
664 { volume empty$
665 { "" }
666 { "volume" volume tie.or.space.connect
667 series empty$
668 'skip$
669 { " of " * series emphasize * }
670 if$
671 "volume and number" number either.or.check
672 }
673 if$
674 }
675 The code in a .bst file contains the complete step-by-step instruc‐
677 tions on how to create the formatted bibliography from the given
678 bibliography data and citation keys. For example, a READ command
679 tells Pybtex to read the bibliography data from all files specified
680 by \bibdata commands in the .aux file, an ITERATE command tells Pyb‐
681 tex to execute a piece of code for each citation key specified by
682 \citation commands, and so on. The built-in write$ function tells
683 Pybtex to write the given string into the resulting .bbl file. Pyb‐
684 tex implements all these commands and built-in functions and simply
685 executes the .bst program step by step.
686 A complete reference of the .bst language can be found in the BibTeX
688 hacking guide by Oren Patashnik. It is available by running texdoc
689 btxhak in most TeX distributions.
690 Python engine
692 The Python engine is enabled by running pybtex with the -l python
693 option.
694 Differences from the BibTeX engine
696 · Formatting styles are written in Python instead of the .bst language.
697 · Formatting styles are not tied to LaTeX and do not use hardcoded
699 LaTeX markup. Instead of that they produce format-agnostic pyb‐
700 tex.richtext.Text objects that can be converted to any markup format
701 (LaTeX, Markdown, HTML, etc.).
702 · Name formatting, label formatting, and sorting styles are defined
704 separately from the main style.
705 How it works
707 When you type pybtex -l python mydocument, this things happen:
708 1. Pybtex reads the file mydocument.aux in the current directory and
710 extracts the name of the the bibliography style, the list of bibli‐
711 ography data files and the list of citation keys. This step is
712 exactly the same as with the BibTeX engine.
713 2. Pybtex reads the biliography data from all data files specified in
715 the .aux file into a single BibliographyData object.
716 3. Then the formatting style is loaded. The formatting style is a
718 Python class with a format_bibliography() method. Pybtex passes the
719 bibliography data (a BibliographyData object) and the list of cita‐
720 tion keys to format_bibliography().
721 4. The formatting style formats each of the requested bibliography
723 entries in a style-specific way.
724 When it comes to formatting names, a name formatting style is loaded
726 and used. A name formatting style is also a Python class with a spe‐
727 cific interface. Similarly, a label formatting style is used to
728 format entry labels, and a sorting style is used to sort the result‐
729 ing style. Each formatting style has a default name style, a
730 default label style and a default sorting style. The defaults can be
731 overridden with options passed to the main style class.
732 Each formatted entry is put into a FormattedEntry object which is
734 just a container for the formatted label, the formatted entry text
735 (a pybtex.richtext.Text object) and the entry key. The reason that
736 the label, the key and the main text are stored separately is to
737 give the output backend more flexibility when converting the Format‐
738 tedEntry object to the actual markup. For example, the HTML backend
739 may want to format the bibliography as a definition list, the LaTeX
740 backend would use \bibitem[label]{key} text constructs, etc.
741 Formatted entries are put into a FormattedBibliography object—it
743 simply contains a list of FormattedEntry objects and some additional
744 metadata.
745 5. The resulting FormattedBibliography is passed to the output backend.
747 The default backend is LaTeX. It can be changed with the pybtex
748 --output-backend option. The output backend converts the formatted
749 bibliography to the specific markup format and writes it to the out‐
750 put file.
751 Python API
753 The base interface
754 Both the Python engine and the BibTeX engine use the same interface
755 defined in pybtex.Engine.
756 pybtex.Engine has a handful of methods but most of them are just conve‐
758 nience wrappers for Engine.format_from_files() that does the actual
759 job.
760 class pybtex.Engine
762 make_bibliography(aux_filename, style=None, output_encod‐
764 ing=None, bib_format=None, **kwargs)
765 Read the given .aux file and produce a formatted bibliog‐
766 raphy using format_from_files().
767 Parameters
769 style – If not None, use this style instead of
770 specified in the .aux file.
771 format_from_string(bib_string, *args, **kwargs)
773 Parse the bigliography data from the given string and
774 produce a formated bibliography using
775 format_from_files().
776 This is a convenience method that calls
778 format_from_strings() with a single string.
779 format_from_strings(bib_strings, *args, **kwargs)
781 Parse the bigliography data from the given strings and
782 produce a formated bibliography.
783 This is a convenience method that wraps each string into
785 a StringIO, then calls format_from_files().
786 format_from_file(filename, *args, **kwargs)
788 Read the bigliography data from the given file and pro‐
789 duce a formated bibliography.
790 This is a convenience method that calls
792 format_from_files() with a single file. All extra argu‐
793 ments are passed to format_from_files().
794 format_from_files(**kwargs)
796 Read the bigliography data from the given files and pro‐
797 duce a formated bibliography.
798 This is an abstract method overridden by both
800 pybtex.PybtexEngine and pybtex.bibtex.BibTeXEngine.
801 The BibTeXEngine class
803 The BibTeX engine lives in the pybtex.bibtex module. The public inter‐
804 face consists of the BibTeXEngine class and a couple of convenience
805 functions.
806 class pybtex.bibtex.BibTeXEngine
808 The Python fomatting engine.
809 See pybtex.Engine for inherited methods.
811 format_from_files(bib_files_or_filenames, style, cita‐
813 tions=['*'], bib_format=None, bib_encoding=None, output_encod‐
814 ing=None, bst_encoding=None, min_crossrefs=2, output_file‐
815 name=None, add_output_suffix=False, **kwargs)
816 Read the bigliography data from the given files and pro‐
817 duce a formated bibliography.
818 Parameters
820 · bib_files_or_filenames – A list of file names or
822 file objects.
823 · style – The name of the formatting style.
825 · citations – A list of citation keys.
827 · bib_format – The name of the bibliography for‐
829 mat. The default format is bibtex.
830 · bib_encoding – Encoding of bibliography files.
832 · output_encoding – Encoding that will be used by
834 the output backend.
835 · bst_encoding – Encoding of the .bst file.
837 · min_crossrefs – Include cross-referenced entries
839 after this many crossrefs. See BibTeX manual for
840 details.
841 · output_filename – If None, the result will be
843 returned as a string. Else, the result will be
844 written to the specified file.
845 · add_output_suffix – Append a .bbl suffix to the
847 output file name.
848 pybtex.bibtex.make_bibliography(*args, **kwargs)
850 A convenience function that calls BibTeXEngine.make_bibliogra‐
851 phy().
852 pybtex.bibtex.format_from_string(*args, **kwargs)
854 A convenience function that calls BibTeXEngine.for‐
855 mat_from_string().
856 pybtex.bibtex.format_from_strings(*args, **kwargs)
858 A convenience function that calls BibTeXEngine.for‐
859 mat_from_strings().
860 pybtex.bibtex.format_from_file(*args, **kwargs)
862 A convenience function that calls BibTeXEngine.for‐
863 mat_from_file().
864 pybtex.bibtex.format_from_files(*args, **kwargs)
866 A convenience function that calls
867 BibTeXEngine.format_from_files().
868 The PybtexEngine class
870 The Python engine resides in the pybtex module and uses an interface
871 similar to the BibTeX engine. There is the PybtexEngine class and some
872 convenience functions.
873 class pybtex.PybtexEngine
875 The Python fomatting engine.
876 See pybtex.Engine for inherited methods.
878 format_from_files(bib_files_or_filenames, style, cita‐
880 tions=['*'], bib_format=None, bib_encoding=None, output_back‐
881 end=None, output_encoding=None, min_crossrefs=2, output_file‐
882 name=None, add_output_suffix=False, **kwargs)
883 Read the bigliography data from the given files and pro‐
884 duce a formated bibliography.
885 Parameters
887 · bib_files_or_filenames – A list of file names or
889 file objects.
890 · style – The name of the formatting style.
892 · citations – A list of citation keys.
894 · bib_format – The name of the bibliography for‐
896 mat. The default format is bibtex.
897 · bib_encoding – Encoding of bibliography files.
899 · output_backend – Which output backend to use.
901 The default is latex.
902 · output_encoding – Encoding that will be used by
904 the output backend.
905 · bst_encoding – Encoding of the .bst file.
907 · min_crossrefs – Include cross-referenced entries
909 after this many crossrefs. See BibTeX manual for
910 details.
911 · output_filename – If None, the result will be
913 returned as a string. Else, the result will be
914 written to the specified file.
915 · add_output_suffix – Append default suffix to the
917 output file name (.bbl for LaTeX, .html for
918 HTML, etc.).
919 pybtex.make_bibliography(*args, **kwargs)
921 A convenience function that calls PybtexEngine.make_bibliogra‐
922 phy().
923 pybtex.format_from_string(*args, **kwargs)
925 A convenience function that calls PybtexEngine.for‐
926 mat_from_string().
927 pybtex.format_from_strings(*args, **kwargs)
929 A convenience function that calls PybtexEngine.for‐
930 mat_from_strings().
931 pybtex.format_from_file(*args, **kwargs)
933 A convenience function that calls PybtexEngine.for‐
934 mat_from_file().
935 pybtex.format_from_files(*args, **kwargs)
937 A convenience function that calls
938 PybtexEngine.format_from_files().
939 Designing styles
941 · Rich text
942 · Rich text classes
944 · Style API
946 · Template language
948 Rich text
950 Pybtex has a set of classes for working with formatted text and produc‐
951 ing formatted output. A piece of formatted text in Pybtex is repre‐
952 sented by a Text object. A Text is basically a container that holds a
953 list of
954 · plain text parts, represented by String objects,
956 · formatted parts, represented by Tag and HRef objects.
958 The basic workflow is:
960 1. Construct a Text object.
962 2. Render it as LaTeX, HTML or other markup.
964 >>> from pybtex.richtext import Text, Tag
966 >>> text = Text('How to be ', Tag('em', 'a cat'), '.')
967 >>> print(text.render_as('html'))
968 How to be <em>a cat</em>.
969 >>> print(text.render_as('latex'))
970 How to be \emph{a cat}.
971 Rich text classes
973 There are several rich text classes in Pybtex:
974 · Text
976 · String
978 · Tag
980 · HRef
982 · Protected
984 Text is the top level container that may contain String, Tag, and HRef
986 objects. When a Text object is rendered into markup, it renders all of
987 its child objects, then concatenates the result.
988 String is just a wrapper for a single Python string.
990 Tag and HRef are also containers that may contain other String, Tag,
992 and HRef objects. This makes nested formatting possible. For example,
993 this stupidly formatted text:
994 Comprehensive TeX Archive Network is comprehensive.
995 is represented by this object tree:
997 >>> text = Text(
999 ... HRef('https://ctan.org/', Tag('em', 'Comprehensive'), ' TeX Archive Network'),
1000 ... ' is ',
1001 ... Tag('em', 'comprehensive'),
1002 ... '.',
1003 ... )
1004 >>> print(text.render_as('html'))
1005 <a href="https://ctan.org/"><em>Comprehensive</em> TeX Archive Network</a> is <em>comprehensive</em>.
1006 Protected represents a “protected” piece of text, something like
1008 {braced text} in BibTeX. It is not affected by case-changing opera‐
1009 tions, like Text.upper() or Text.lower(), and is not splittable by
1010 Text.split().
1011 All rich text classes share the same API which is more or less similar
1013 to plain Python strings.
1014 Like Python strings, rich text objects are supposed to be immutable.
1016 Methods like Text.append() or Text.upper() return a new Text object
1017 instead of modifying the data in place. Attempting to modify the con‐
1018 tents of an existing Text object is not supported and may lead to weird
1019 results.
1020 Here we document the methods of the Text class. The other classes have
1022 the same methods.
1023 class pybtex.richtext.Text(*parts)
1025 The Text class is the top level container that may contain
1026 String, Tag or HRef objects.
1027 __init__(*parts)
1029 Create a text object consisting of one or more parts.
1030 Empty parts are ignored:
1032 >>> Text() == Text('') == Text('', '', '')
1034 True
1035 >>> Text('Word', '') == Text('Word')
1036 True
1037 Text() objects are unpacked and their children are
1039 included directly:
1040 >>> Text(Text('Multi', ' '), Tag('em', 'part'), Text(' ', Text('text!')))
1042 Text('Multi ', Tag('em', 'part'), ' text!')
1043 >>> Tag('strong', Text('Multi', ' '), Tag('em', 'part'), Text(' ', 'text!'))
1044 Tag('strong', 'Multi ', Tag('em', 'part'), ' text!')
1045 Similar objects are merged together:
1047 >>> Text('Multi', Tag('em', 'part'), Text(Tag('em', ' ', 'text!')))
1049 Text('Multi', Tag('em', 'part text!'))
1050 >>> Text('Please ', HRef('/', 'click'), HRef('/', ' here'), '.')
1051 Text('Please ', HRef('/', 'click here'), '.')
1052 __eq__(other)
1054 Rich text objects support equality comparison:
1055 >>> Text('Cat') == Text('cat')
1057 False
1058 >>> Text('Cat') == Text('Cat')
1059 True
1060 __len__()
1062 len(text) returns the number of characters in the text,
1063 ignoring the markup:
1064 >>> len(Text('Long cat'))
1066 8
1067 >>> len(Text(Tag('em', 'Long'), ' cat'))
1068 8
1069 >>> len(Text(HRef('http://example.com/', 'Long'), ' cat'))
1070 8
1071 __contains__(item)
1073 value in text returns True if any part of the text con‐
1074 tains the substring value:
1075 >>> 'Long cat' in Text('Long cat!')
1077 True
1078 Substrings splitted across multiple text parts are not
1080 matched:
1081 >>> 'Long cat' in Text(Tag('em', 'Long'), 'cat!')
1083 False
1084 __getitem__(key)
1086 Slicing and extracting characters works like with regular
1087 strings, formatting is preserved.
1088 >>> Text('Longcat is ', Tag('em', 'looooooong!'))[:15]
1090 Text('Longcat is ', Tag('em', 'looo'))
1091 >>> Text('Longcat is ', Tag('em', 'looooooong!'))[-1]
1092 Text(Tag('em', '!'))
1093 __add__(other)
1095 Concatenate this Text with another Text or string.
1096 >>> Text('Longcat is ') + Tag('em', 'long')
1098 Text('Longcat is ', Tag('em', 'long'))
1099 add_period(period='.')
1101 Add a period to the end of text, if the last character is
1102 not “.”, “!” or “?”.
1103 >>> text = Text("That's all, folks")
1105 >>> print(six.text_type(text.add_period()))
1106 That's all, folks.
1107 >>> text = Text("That's all, folks!")
1109 >>> print(six.text_type(text.add_period()))
1110 That's all, folks!
1111 append(text)
1113 Append text to the end of this text.
1114 For Tags, HRefs, etc. the appended text is placed inside
1116 the tag.
1117 >>> text = Tag('strong', 'Chuck Norris')
1119 >>> print((text + ' wins!').render_as('html'))
1120 <strong>Chuck Norris</strong> wins!
1121 >>> print(text.append(' wins!').render_as('html'))
1122 <strong>Chuck Norris wins!</strong>
1123 capfirst()
1125 Capitalize the first letter of the text.
1126 >>> Text(Tag('em', 'long Cat')).capfirst()
1128 Text(Tag('em', 'Long Cat'))
1129 capitalize()
1131 Capitalize the first letter of the text and lowercase the
1132 rest.
1133 >>> Text(Tag('em', 'LONG CAT')).capitalize()
1135 Text(Tag('em', 'Long cat'))
1136 endswith(suffix)
1138 Return True if the text ends with the given suffix.
1139 >>> Text('Longcat!').endswith('cat!')
1141 True
1142 Suffixes split across multiple parts are not matched:
1144 >>> Text('Long', Tag('em', 'cat'), '!').endswith('cat!')
1146 False
1147 isalpha()
1149 Return True if all characters in the string are alpha‐
1150 betic and there is at least one character, False other‐
1151 wise.
1152 join(parts)
1154 Join a list using this text (like string.join)
1155 >>> letters = ['a', 'b', 'c']
1157 >>> print(six.text_type(String('-').join(letters)))
1158 a-b-c
1159 >>> print(six.text_type(String('-').join(iter(letters))))
1160 a-b-c
1161 lower()
1163 Convert rich text to lowercase.
1164 >>> Text(Tag('em', 'Long cat')).lower()
1166 Text(Tag('em', 'long cat'))
1167 render(backend)
1169 Render this Text into markup.
1170 Parameters
1172 backend – The formatting backend (an instance of
1173 pybtex.backends.BaseBackend).
1174 render_as(backend_name)
1176 Render this Text into markup. This is a wrapper method
1177 that loads a formatting backend plugin and calls
1178 Text.render().
1179 >>> text = Text('Longcat is ', Tag('em', 'looooooong'), '!')
1181 >>> print(text.render_as('html'))
1182 Longcat is <em>looooooong</em>!
1183 >>> print(text.render_as('latex'))
1184 Longcat is \emph{looooooong}!
1185 >>> print(text.render_as('text'))
1186 Longcat is looooooong!
1187 Parameters
1189 backend_name – The name of the output backend
1190 (like "latex" or "html").
1191 split(sep=None, keep_empty_parts=None)
1193 >>> Text('a + b').split()
1195 [Text('a'), Text('+'), Text('b')]
1196 >>> Text('a, b').split(', ')
1198 [Text('a'), Text('b')]
1199 startswith(prefix)
1201 Return True if the text starts with the given prefix.
1202 >>> Text('Longcat!').startswith('Longcat')
1204 True
1205 Prefixes split across multiple parts are not matched:
1207 >>> Text(Tag('em', 'Long'), 'cat!').startswith('Longcat')
1209 False
1210 upper()
1212 Convert rich text to uppsercase.
1213 >>> Text(Tag('em', 'Long cat')).upper()
1215 Text(Tag('em', 'LONG CAT'))
1216 class pybtex.richtext.String(*parts)
1218 A String is a wrapper for a plain Python string.
1219 >>> from pybtex.richtext import String
1221 >>> print(String('Crime & Punishment').render_as('text'))
1222 Crime & Punishment
1223 >>> print(String('Crime & Punishment').render_as('html'))
1224 Crime & Punishment
1225 String supports the same methods as Text.
1227 class pybtex.richtext.Tag(name, *args)
1229 A Tag represents something like an HTML tag or a LaTeX format‐
1230 ting command:
1231 >>> from pybtex.richtext import Tag
1233 >>> tag = Tag('em', 'The TeXbook')
1234 >>> print(tag.render_as('html'))
1235 <em>The TeXbook</em>
1236 >>> print(tag.render_as('latex'))
1237 \emph{The TeXbook}
1238 Tag supports the same methods as Text.
1240 class pybtex.richtext.HRef(url, *args)
1242 A HRef represends a hyperlink:
1243 >>> from pybtex.richtext import Tag
1245 >>> href = HRef('http://ctan.org/', 'CTAN')
1246 >>> print(href.render_as('html'))
1247 <a href="http://ctan.org/">CTAN</a>
1248 >>> print(href.render_as('latex'))
1249 \href{http://ctan.org/}{CTAN}
1250 >>> href = HRef(String('http://ctan.org/'), String('http://ctan.org/'))
1252 >>> print(href.render_as('latex'))
1253 \url{http://ctan.org/}
1254 HRef supports the same methods as Text.
1256 class pybtex.richtext.Protected(*args)
1258 A Protected represents a “protected” piece of text.
1259 · Protected.lower(), Protected.upper(), Protected.capitalize(),
1261 and Protected.capitalize() are no-ops and just return the
1262 Protected object itself.
1263 · Protected.split() never splits the text. It always returns a
1265 one-element list containing the Protected object itself.
1266 · In LaTeX output, Protected is {surrounded by braces}. HTML
1268 and plain text backends just output the text as-is.
1269 >>> from pybtex.richtext import Protected
1271 >>> text = Protected('The CTAN archive')
1272 >>> text.lower()
1273 Protected('The CTAN archive')
1274 >>> text.split()
1275 [Protected('The CTAN archive')]
1276 >>> print(text.render_as('latex'))
1277 {The CTAN archive}
1278 >>> print(text.render_as('html'))
1279 <span class="bibtex-protected">The CTAN archive</span>
1280 New in version 0.20.
1282 class pybtex.richtext.Symbol(name)
1285 A special symbol. This class is rarely used and may be removed
1286 in future versions.
1287 Examples of special symbols are non-breaking spaces and dashes.
1289 Symbol supports the same methods as Text.
1291 Style API
1293 A formatting style in Pybtex is a class inherited from
1294 pybtex.style.formatting.BaseStyle.
1295 class pybtex.style.formatting.BaseStyle(label_style=None,
1297 name_style=None, sorting_style=None, abbreviate_names=False, min_cross‐
1298 refs=2, **kwargs)
1299 The base class for pythonic formatting styles.
1300 format_bibliography(bib_data, citations=None)
1302 Format bibliography entries with the given keys and
1303 return a FormattedBibliography object.
1304 Parameters
1306 · bib_data – A pybtex.database.BibliographyData
1308 object.
1309 · citations – A list of citation keys.
1311 Pybtex loads the style class as a plugin, instantiates it with proper
1313 parameters and calls the format_bibliography() method that does the
1314 actual formatting job. The default implementation of
1315 format_bibliography() calls a format_<type>() method for each bibliog‐
1316 raphy entry, where <type> is the entry type, in lowercase. For example,
1317 to format an entry of type book, the format_book() method is called.
1318 The method must return a Text object. Style classes are supposed to
1319 implement format_<type>() methods for all entry types they support. If
1320 a formatting method is not found for some entry, Pybtex complains about
1321 unsupported entry type.
1322 An example minimalistic style:
1324 from pybtex.style.formatting import BaseStyle
1326 from pybtex.richtext import Text, Tag
1327 class MyStyle(BaseStyle):
1329 def format_article(self, entry):
1330 return Text('Article ', Tag('em', entry.fields['title']))
1331 Template language
1333 Manually creating Text objects may be tedious. Pybtex has a small tem‐
1334 plate language to simplify common formatting tasks, like joining words
1335 with spaces, adding commas and periods, or handling missing fields.
1336 The template language is is not very documented for now, so you should
1338 look at the code in the pybtex.style.template module and the existing
1339 styles.
1340 An example formatting style using template language:
1342 from pybtex.style.formatting import BaseStyle, toplevel
1344 from pybtex.style.template import field, join, optional
1345 class MyStyle(BaseStyle):
1347 def format_article(self, entry):
1348 if entry.fields['volume']:
1349 volume_and_pages = join [field('volume'), optional [':', pages]]
1350 else:
1351 volume_and_pages = words ['pages', optional [pages]]
1352 template = toplevel [
1353 self.format_names('author'),
1354 sentence [field('title')],
1355 sentence [
1356 tag('emph') [field('journal')], volume_and_pages, date],
1357 ]
1358 return template.format_data(entry)
1359 Extending Pybtex with plugins
1361 · Entry points
1362 · pybtex.database.input
1364 · pybtex.database.output
1366 · pybtex.backends
1368 · pybtex.style.formatting
1370 · pybtex.style.labels
1372 · pybtex.style.names
1374 · pybtex.style.sorting
1376 · Registering plugins
1378 · Example plugins
1380 Pybtex uses plugins for bibliography data formats, output markup for‐
1382 mats and bibliography formatting styles. This allows to add new formats
1383 or styles to Pybtex withoud modifying Pybtex itself.
1384 The plugins are based on Setuptools’ entry points.
1386 Entry points
1388 Here is the list of entry points supported by Pybtex.
1389 pybtex.database.input
1391 This entry point is used for bibliography parsers. Must point to a
1392 subclass of pybtex.database.input.BaseParser.
1393 There is also an additional entry point called pybtex.database.out‐
1395 put.suffixes. It is used for registering bibliography formats for spe‐
1396 cific file suffixes (like BibTeX for .bib files).
1397 For example, a JSON input plugin could use these entry points:
1399 [pybtex.database.input]
1401 json = pybtexjson:JSONParser
1402 [pybtex.database.input.suffixes]
1404 .json = pybtexjson:JSONParser
1405 pybtex.database.output
1407 This entry poing is used for bibliography writers. Must point to a
1408 subclass of pybtex.database.output.BaseWriter.
1409 There is also an additional entry point called pybtex.database.out‐
1411 put.suffixes. It is used for registering default plugins for specific
1412 file suffixes in the same way as pybtex.database.input.suffixes
1413 described above.
1414 pybtex.backends
1416 This entry point is for adding new output markup formats for Pythonic
1417 bibliography styles. The built-in plugins are latex, html, markdown,
1418 and plaintext. Must point to a pybtex.backends.BaseBackend subclass.
1419 pybtex.style.formatting
1421 This is the entry point for Pythonic bibliography styles. Must point to
1422 a pybtex.style.formatting.BaseStyle subclass.
1423 pybtex.style.labels
1425 Label styles for Pythonic bibliography styles.
1426 pybtex.style.names
1428 Name styles for Pythonic bibliography styles.
1429 pybtex.style.sorting
1431 Sorting styles for Pythonic bibliography styles.
1432 Registering plugins
1434 See Setuptools’ documentation.
1435 Example plugins
1437 An example project directory with two simple plugins and a setup.py
1438 file can be found in the examples/sample_plugins subdirectory.
1439
1441 Version 0.22.2
1442 (released on January 17, 2019)
1443 · Fixed compatibility with Python 2 and older versions of Python 3.
1445 Version 0.22.1
1447 (released on January 16, 2019)
1448 · Fixed non-working --backend option with pybtex -l python.
1450 Version 0.22.0
1452 (released on November 18, 2018)
1453 · Fixed handling of duplicate fields in .bib biles. Thanks, Jannik
1455 Schürg!
1456 · BibTeX parser is now up to 10% faster on some files. Thanks, Fabrice
1458 Benhamouda!
1459 · Fixed parsing of names with \~ characters.
1461 · Fixed formatting proceedings without an editor field in unsrt.py.
1463 · In case of too many braces in a BibTeX string, PybtexSyntaxError is
1465 now raised instead of RecursionError.
1466 · Dropped 2to3, made the code compatible with both Python 2 and 3 with
1468 Six.
1469 · Moved tests outside of the pybtex package.
1471 · Fixed searching in docs with recent versions of Sphinx.
1473 · API: renamed bibtex.BibTeXEntryIterator to bibtex.LowLevelParser for
1475 clarity.
1476 · API: removed confusing usage of Person.text in tempate.names.
1478 · API: Entry.fields does not automagically look for cross-referenced
1480 entries anymore.
1481 Version 0.21
1483 (released on January 20, 2017)
1484 · BibTeX writer now uses latexcodec to encode characters that are not
1486 directly supported by the output encoding. Thanks, Hong Xu!
1487 · HTML backend: {braced stings} are now wrapped with <span class="bib‐
1489 tex-protected"> to enable custom CSS styling.
1490 · unsrt.py: DOI, PubMed and Arxiv links now use HTTPS instead of HTTP.
1492 · unsrt.py: URLs with percent characters are now formatted correctly.
1494 · unsrt.py: short page / volume / chapter numbers are now joined with a
1496 non-breaking space, like in BibTeX.
1497 · unsrt.py: inbook now uses the editor field if the author field is
1499 missing, like in BibTeX.
1500 · unsrt.py: the words “volume” and “pages” in the beginning of the sen‐
1502 tence are now capitalized, like in BibTeX.
1503 · unsrt.py: removed unnecessary period between the book title and the
1505 comma in inbook.
1506 Version 0.20.1
1508 (released on March 17, 2016)
1509 · LaTeX backend: fix encoding tilde ("~") characters with newer ver‐
1511 sions of latexcodec.
1512 · Fix splitting names with escaped space ("\ ") characters.
1514 Version 0.20
1516 (released on March 10, 2016)
1517 · YAML reader and writer now preserve the order of bibliography
1519 entries.
1520 · Improved URL formatting in pythonic styles.
1522 · Built-in pythonic styles now support the ISBN field.
1524 · Pythonic styles now treat LaTeX braces correctly:
1526 · case conversion does not affect {braced substrings},
1528 · braces are stripped from non-LaTeX output: "{P}ython" becomes
1530 "Python".
1531 · Pythonic styles now use latexcodec to decode LaTeX markup. For exam‐
1533 ple, "Schr\"odinger" is now correctly rendered as "Schrödinger" in
1534 HTML or plain text.
1535 Thanks to Hong Xu for his contributions!
1537 Version 0.19
1539 (released on October 26, 2015)
1540 · Added Markdown output format (contributed by Jorrit Wronski).
1542 · Incorrectly formatted author and editor names now result in warnings
1544 instead of errors, unless --strict mode is enabled.
1545 · Fixed HTML escaping.
1547 · Fixed parsing nested .aux files.
1549 · Fixed splitting names separated by non-lowercase " and ".
1551 · Fixed line numbers in error messages when parsing strings with
1553 DOS/Windows line breaks.
1554 · Fixed compatibility with BibTeX when parsing certain weird “von”
1556 names.
1557 · Removed excessive trailing newline from .bib output.
1559 · Text wrapping now works exactly as in BibTeX.
1561 · Added new API for reading and writing bibliography data.
1563 · Pythonic styles: reworked and extended the rich text API.
1565 · Pythonic styles: added strong, i, b, tt tags, renamed the old emph
1567 tag to em.
1568 · Pythonic styles: the author_year_title style now returns "" instead
1570 of None (fixes unorderable types error in Python 3).
1571 · Ported the documentation to Sphinx.
1573 Thanks to Jorrit Wronski and Matthias Troffaes for their fixes and
1575 improvements!
1576 Version 0.18
1578 (released on July 6, 2014)
1579 · Pybtex is now fully case-insensitive (like BibTeX). As a consequence,
1581 IEEEtran styles now work correctly.
1582 · Added --preserve-case option to pybtex-convert (default behavior is
1584 to converted all identifiers to lower case).
1585 · An error is reported if two citations have the same key but different
1587 case, like in BibTeX. (Example: ddt1999 and DDT1999).
1588 · Fixed parsing unused bibliography entries with strings containing @
1590 characters.
1591 · entry.max$ constant is now set to 250, global.max$ is set to 20000,
1593 like in BibTeX.
1594 · Added --strict option to pybtex-convert and pybtex-format (turns
1596 warning into errors).
1597 · Strict mode is now enabled by default when using pybtex as a library
1599 (exceptions are raised on all errors instead of just printing warn‐
1600 ings to stderr).
1601 Non-strict error handling is still enabled when using pybtex from the
1603 command line, for compatibility with BibTeX. Use --strict option if
1604 you don’t like this.
1605 · Added missing pybtex-format manpage.
1607 Version 0.17
1609 (released on March 10, 2014)
1610 · Added pybtex-format utility for formatting bibliography files as
1612 HTML, LaTeX, and other supported human-readable formats.
1613 · Added --strict command line option to pybtex (all warnings become
1615 errors).
1616 · Added alpha label style, and alpha and unsrtalpha formatting styles.
1618 · Added support for url, eprint, doi, and pubmed fields in unsrt style.
1620 · Names with hyphens are now abbreviated correctly (“Jean-Baptiste”
1622 becomes “J.-B.”).
1623 · width$ now uses cmr10 font metrics, like in BibTeX. Non-latin charac‐
1625 ters are also supported.
1626 · Pythonic style engine now supports @preamble commands.
1628 · Warning on missing fields are now more human-readable.
1630 · When writing BibTeX files, put entry key on the same line with entry
1632 type. Fixes warnings in Jabref.
1633 · When using multiple .bib files, macros defined in earlier files are
1635 available in subsequent ones (like in BibTeX).
1636 · Fixed parsing .bst files with lines consisting of a single % charac‐
1638 ter.
1639 · Fixed sorting entries without author in author_year_title sorting
1641 style.
1642 · Fixed broken CaseInsensitiveDict.get().
1644 · CaseInsensitiveDict is now pickleable.
1646 · Added support for registering plugins at runtime with pybtex.plug‐
1648 in.register_plugin() - useful for using pybtex as a library.
1649 Many thanks to Matthias C. M. Troffaes for his numerous fixes and
1651 improvements!
1652 Version 0.16
1654 (released on March 17, 2012)
1655 · BibTeX .bib and .bst parsers were completely rewritten. They are now
1657 much faster and more BibTeX-compatible.
1658 · Syntax errors and undefined strings in .bib files now result in warn‐
1660 ings instead of errors, like in BibTeX.
1661 · Unused entries in .bib files are now skipped, like in BibTeX.
1663 · The case of entry keys is now preserved (in previous versions they
1665 were converted to lowercase).
1666 · Pythonic style engine now supports sorting.
1668 · Pythonic style engine: fixed nested optional() blocks.
1670 · Fixed parsing of some names with a Last part but no von part.
1672 · Fixed processing of brace-level-one “special characters” in purify$
1674 BibTeX built-in function.
1675 · Added proper error messages on encoding errors in .bib files.
1677 · The default encoding is now UTF-8 on all platforms.
1679 · pybtex-convert now preserves the order of entries in BibTeX and Bib‐
1681 TeXML files.
1682 The following changes were contributed by Matthias C. M. Troffaes:
1684 · Fixed first_of behavior when non-empty child is followed by a child
1686 that has a missing field.
1687 · Fixed crossref lookups when key is not lower case.
1689 · Completed unsrt and plain python styles: they now contain all entry
1691 types.
1692 · Added doctree backend for rendering into a tree of docutils nodes.
1694 · Added support for non-string backends.
1696 Version 0.15
1698 (released on February 1, 2011)
1699 · Changed license from GPL-3 to MIT.
1701 · Added support for setuptools plugins.
1703 · BibTeX parser: fixed whitespace normalization in concatenated
1705 strings.
1706 · BibTeX parser: when parsing multiple BibTeX files, macros defined in
1708 earlier files are now available to all subsequent files, like in Bib‐
1709 TeX.
1710 · BibTeX .bst interpreter now prints warnings on missing entries, like
1712 BibTeX, instead of raising a KeyError.
1713 · call.type$ BibTeX built-in function now uses default.entry for
1715 unknown entry types, like in BibTeX.
1716 · substring$ now accepts start=0 and returns an empty string.
1718 · change.case$: fixed incorrect formatting of strings starting with
1720 special characters with "t" format.
1721 · Fixed abbreviation of names starting with special characters or
1723 non-alphabetic characters.
1724 · Fixed incorrect entry order and duplicated entries with \nocite{*}.
1726 · Added more detailed error messages for already defined variables in
1728 .bst files.
1729 Version 0.14.1
1731 (released on September 30, 2010)
1732 · Added missing custom_fixers directory to the tarball — needed only
1734 for converting the sources to Python 3.
1735 Version 0.14
1737 (released on September 20, 2010)
1738 · BibTeX writer: fixed quoting " (double quote) characters.
1740 · BibTeX parser now produces human-readable error messages on unread
1742 macros.
1743 · Added error messages on missing data in .aux files.
1745 · Improved performance on very long name lists.
1747 · Added support for Python 3.
1749 Version 0.13.2
1751 (released on February 26, 2010)
1752 · BibTeX parser: fixed a bug with parsing strings containing braces,
1754 like "Error in {DNA}".
1755 Version 0.13.1
1757 (released on February 18, 2010)
1758 · Fixed ImportError: No module named kpathsea errors. One of the source
1760 files was missing from pybtex-0.13.tar.bz2 for some strange reason.
1761 Sorry about that. ;)
1762 Version 0.13
1764 (released on February 14, 2010)
1765 · Implemented --min-crossrefs option.
1767 · All command line options of the original BibTeX are not supported.
1769 · Pybtex now respects BSTINPUTS, BIBINPUTS and TEXMFOUTPUT environment
1771 variables.
1772 · BibTeX bibliography parser now strips excessive whitespace from
1774 fields, like BibTeX does.
1775 Version 0.12
1777 (released on November 21, 2009)
1778 · Pybtex now works correctly with \input{filename} in LaTeX files.
1780 · Added a proper change.case$ BibTeX function instead of a stub.
1782 · Added -e/--encoding command line option.
1784 · Fixed non-working --bibtex-encoding option.
1786 · Added proper error messages on missing plugins, file IO errors, some
1788 BibTeX interpreter errors, etc.
1789 · Fallback to backslash-encoding when printing messages to the console
1791 - to make them printable regardless of the locale.
1792 Version 0.11
1794 (released on September 7, 2009)
1795 · Made text.lentgh$ and text.prefix$ BibTeX built-in functions treat
1797 braces and TeX special characters properly (like the original BibTeX
1798 functions do).
1799 · Changed purify$ to replace ties and hyphens by spaces.
1801 · Fixed a bug in substring$ with negative start values.
1803 · Fixed .bst file grammar to allow underscores in identifiers.
1805 · BibTeX name parser: ties are now treated as whitespace when splitting
1807 name parts.
1808 · Implemented BibTeX-like text wrapping. The resulting .bbl output
1810 should now be byte-for-byte identical to that of BibTeX in most
1811 cases.
1812 Version 0.10
1814 (released on August 24, 2009)
1815 · Added support for multiple bibliography databases.
1817 · Pythonic bibliography formatter: added helper functions to simplify
1819 writing BibTeX-like name formatting styles in Python. Added a tool
1820 for automatic conversion of BibTeX {ll}{, ff}-like patterns into
1821 Python.
1822 · BibTeX parser: added missing characters to the caracter set of the
1824 valid identifiers.
1825 · BibTeX parser: a comma is now allowed between the last field and the
1827 closing brace.
1828 · BibTeX name parser: when splitting name parts into words, whitespace
1830 at brace level > 0 is now ignored.
1831 · BibTeX name parser: fixed parsing of single-word lowercase names and
1833 complex von names, like in “Andrea de Leeuw van Weenen”.
1834 · Fixed broken --label-style and --name-style options.
1836 · Added (autogenerated) manpages.
1838 · Added this changelog.
1840 Version 0.9
1842 (released on August 17, 2009)
1843 · Implemented \citation{*}.
1845 · Implemented crossrefs.
1847 · BibTeX .bib parser now supports newlines inside strings.
1849 · Fixed: .bib filename from .aux file was ignored.
1851 · Fixed incorrect argument passing to codecs.open().
1853 · Fixed incorrect whitespace handling in the name parsing code.
1855 Version 20090402
1857 (released on February 04, 2009)
1858 · Fixed yet more encoding-related bugs.
1860 · Cleaned up some old nasty code, updated the documentation, added more
1862 tests.
1863 Version 20080918
1865 (released on September 18, 2008)
1866 · Added HTML backend. The pythonic bibliography formatter can now pro‐
1868 duce LaTeX, HTML, and plaintext.
1869 · BibTeXML writer now indents the resulting XML.
1871 · Removed the dependency on external elementtree.
1873 · Improved the interface of the pybtex-convert script. It is just con‐
1875 vert foo.bib foo.yaml now.
1876 · Fixed several bugs in the BibTeX interpreter.
1878 · Fixed several encoding-related bugs.
1880 Version 20070513
1882 (released on May 13, 2007)
1883 · Added an interpreter for the BibTeX stack language. Pybtex now sup‐
1885 ports BibTeX style files.
1886 · Added a YAML bibliography format (both input and output).
1888 · Improved processing of names with {braces}.
1890 · Added support for @preamble to both BibTeX parser and writer.
1892 · Introduced an experimental pythonic template language to make bibli‐
1894 ography formatting easier with a more functional-oriented approach.
1895 · Added support for incollection entries to the experimentl pythonic
1897 bibliography style.
1898 · cElementTree is now used for BibTeXML parsing, if present.
1900 · Added some documentation files (finally).
1902 Version 20060416
1904 (released on April 16, 2006)
1905 · Added BibTeX and BibTeXML formatters for bibliography databases.
1907 Added a database conversion tool.
1908 · Improved name splitting in the BibTeX parser.
1910 · Locale encoding is now used by default.
1912 · Added richtext.Check class to simplify formatting of optional bibli‐
1914 ography fields.
1915 · Added support for booklet and inbook entry types to the experimentl
1917 pythonic bibliography style.
1918 Version 20060402
1920 (released on April 2, 2006)
1921 · Added initial Unicode support and input/output encodings.
1923 · Introduced output backends to make bibliography styles markup-inde‐
1925 pendent. Added LaTeX and Plaintext backends.
1926 · Improved BibTeXML parser, add support for pre-parsed names (<bib‐
1928 tex:first>, <bibtex:middle> and so on).
1929 · Added default macros for month names to the BibTeX parser.
1931 · Added an experimental richtext.Phrase (former Pack class (former
1933 Packer class)) class to make creating sentences and delimited lists
1934 easier.
1935 · Added experimental support for pluggable name and label styles to the
1937 pythonic bibliogrphy formatter.
1938 · Made Pybtex work on Windows by renaming aux.py to auxfile.py. Duh.
1940 Version 0.1
1942 (released on March 4, 2006)
1943 Initial release. This version already has a basic BibTeX .bib parser,
1945 BibTeXML parser and a proof-of-concept pythonic bibliography formatter.
1946
1948 Andrey Golovizin
1949
1951 2020, Andrey Golovizin
19520.22.2 Mar 27, 2020 PYBTEX(1)