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 way 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 be 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 \bibliography{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 ported to Python already. 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 op‐
91 tions 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 separately.
112 Pretty-printing bibliography databases with bibtex-format
114 Sometimes you may want to convert a bibliography database to a hu‐
115 man-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
122 changed 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 La‐
209 TeX-only. Pythonic styles in Pybtex are markup-independent and can out‐
210 put 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 au‐
335 thor or an editor).
336 class pybtex.database.BibliographyData(entries=None, preamble=None,
338 wanted_entries=None, min_crossrefs=2)
339 entries
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 classmethod from_string(value, bib_format, **kwargs)
382 Return the data from a unicode string in the given for‐
383 mat.
384 Parameters
386 bib_format – Data format (“bibtex”, “yaml”, etc.).
387 New in version 0.22.2.
389 to_bytes(bib_format, **kwargs)
392 Return the data as a byte string in the given format.
393 Parameters
395 bib_format – Data format (“bibtex”, “yaml”, etc.).
396 New in version 0.19.
398 to_file(file, bib_format=None, **kwargs)
401 Save the data to a file.
402 Parameters
404 • file – A file name or a file-like object.
406 • bib_format – Data format (“bibtex”, “yaml”,
408 etc.). If not specified, Pybtex will try to
409 guess by the file name.
410 New in version 0.19.
412 lower()
415 Return another BibliographyData with all identifiers con‐
416 verted to lowercase.
417 >>> data = parse_string("""
419 ... @BOOK{Obrazy,
420 ... title = "Obrazy z Rus",
421 ... author = "Karel Havlíček Borovský",
422 ... }
423 ... @BOOK{Elegie,
424 ... title = "Tirolské elegie",
425 ... author = "Karel Havlíček Borovský",
426 ... }
427 ... """, 'bibtex')
428 >>> data_lower = data.lower()
429 >>> list(data_lower.entries.keys())
430 ['obrazy', 'elegie']
431 >>> for entry in data_lower.entries.values():
432 ... entry.key
433 ... list(entry.persons.keys())
434 ... list(entry.fields.keys())
435 'obrazy'
436 ['author']
437 ['title']
438 'elegie'
439 ['author']
440 ['title']
441 class pybtex.database.Entry(type_, fields=None, persons=None)
443 A bibliography entry.
444 key = None
446 Entry key (for example, 'fukushima1980neocognitron').
447 type = None
449 Entry type ('book', 'article', etc.).
450 fields = None
452 A dictionary of entry fields. The dictionary is ordered
453 and case-insensitive.
454 persons = None
456 A dictionary of entry persons, by their roles.
457 The most often used roles are 'author' and 'editor'.
459 to_string(bib_format, **kwargs)
461 Return the data as a unicode string in the given format.
462 Parameters
464 bib_format – Data format (“bibtex”, “yaml”, etc.).
465 classmethod from_string(value, bib_format, entry_number=0,
467 **kwargs)
468 Return the data from a unicode string in the given for‐
469 mat.
470 Parameters
472 • bib_format – Data format (“bibtex”, “yaml”,
474 etc.).
475 • entry_number – entry number if the string has
477 more than one.
478 New in version 0.22.2.
480 class pybtex.database.Person(string='', first='', middle='',
483 prelast='', last='', lineage='')
484 A person or some other person-like entity.
485 >>> knuth = Person('Donald E. Knuth')
487 >>> knuth.first_names
488 ['Donald']
489 >>> knuth.middle_names
490 ['E.']
491 >>> knuth.last_names
492 ['Knuth']
493 first_names = None
495 A list of first names.
496 New in version 0.19: Earlier versions used first(), which
498 is now deprecated.
499 middle_names = None
502 A list of middle names.
503 New in version 0.19: Earlier versions used middle(),
505 which is now deprecated.
506 prelast_names = None
509 A list of pre-last (aka von) name parts.
510 New in version 0.19: Earlier versions used middle(),
512 which is now deprecated.
513 last_names = None
516 A list of last names.
517 New in version 0.19: Earlier versions used last(), which
519 is now deprecated.
520 lineage_names = None
523 A list of linage (aka Jr) name parts.
524 New in version 0.19: Earlier versions used lineage(),
526 which is now deprecated.
527 property bibtex_first_names
530 A list of first and middle names together. (BibTeX
531 treats all middle names as first.)
532 New in version 0.19: Earlier versions used
534 Person.bibtex_first(), which is now deprecated.
535 >>> knuth = Person('Donald E. Knuth')
538 >>> knuth.bibtex_first_names
539 ['Donald', 'E.']
540 get_part(type, abbr=False)
542 Get a list of name parts by type.
543 >>> knuth = Person('Donald E. Knuth')
545 >>> knuth.get_part('first')
546 ['Donald']
547 >>> knuth.get_part('last')
548 ['Knuth']
549 property rich_first_names
551 A list of first names converted to rich text.
552 New in version 0.20.
554 property rich_middle_names
557 A list of middle names converted to rich text.
558 New in version 0.20.
560 property rich_prelast_names
563 A list of pre-last (aka von) name parts converted to rich
564 text.
565 New in version 0.20.
567 property rich_last_names
570 A list of last names converted to rich text.
571 New in version 0.20.
573 property rich_lineage_names
576 A list of lineage (aka Jr) name parts converted to rich
577 text.
578 New in version 0.20.
580 first(abbr=False)
583 Deprecated since version 0.19: Use first_names instead.
584 middle(abbr=False)
587 Deprecated since version 0.19: Use middle_names instead.
588 prelast(abbr=False)
591 Deprecated since version 0.19: Use prelast_names instead.
592 last(abbr=False)
595 Deprecated since version 0.19: Use last_names instead.
596 lineage(abbr=False)
599 Deprecated since version 0.19: Use lineage_names instead.
600 bibtex_first()
603 Deprecated since version 0.19: Use bibtex_first_names in‐
604 stead.
605 Formatting bibliographies
608 • BibTeX engine
609 • How it works
611 • Python engine
613 • Differences from the BibTeX engine
615 • How it works
617 • Python API
619 • The base interface
621 • The BibTeXEngine class
623 • The PybtexEngine class
625 The main purpose of Pybtex is turning machine-readable bibliography
627 data into human-readable bibliographies formatted in a specific style.
628 Pybtex reads bibliography data that looks like this:
629 @book{graham1989concrete,
631 title = "Concrete mathematics: a foundation for computer science",
632 author = "Graham, Ronald Lewis and Knuth, Donald Ervin and Patashnik, Oren",
633 year = "1989",
634 publisher = "Addison-Wesley"
635 }
636 and formats it like this:
638 R. L. Graham, D. E. Knuth, and O. Patashnik. Concrete mathematics:
639 a foundation for computer science. Addison-Wesley, 1989.
640 Pybtex contains two different formatting engines:
642 • The BibTeX engine uses BibTeX .bst styles.
644 • The Python engine uses styles written in Python.
646 BibTeX engine
648 The BibTeX engine is fully compatible with BibTeX style files and is
649 used by default.
650 How it works
652 When you type pybtex mydocument, the following things happen:
653 1. Pybtex reads the file mydocument.aux in the current directory. This
655 file is normally created by LaTeX and contains all sorts of auxil‐
656 iary information collected during processing of the LaTeX document.
657 Pybtex is interested in these three pieces of information:
659 Bibliography style:
661 First, Pybtex searches the .aux file for a \bibstyle command
662 that specifies which formatting style will be used.
663 For example, \bibstyle{unsrt} instructs Pybtex to use format‐
665 ting style defined in the file unsrt.bst.
666 Bibliography data:
668 Next, Pybtex expects to find at least one \bibdata command in
669 the .aux file that tells where to look for the bibliography
670 data.
671 For example, \bibdata{mydocument} means “use the bibliography
673 data from mydocument.bib”.
674 Citations:
676 Finally, Pybtex needs to know which entries to put into the
677 resulting bibliography. Pybtex gets the list of citation
678 keys from \citation commands in the .aux file.
679 For example, \citation{graham1989concrete} means “include the
681 entry with the key graham1989concrete into the resulting bib‐
682 liograhy”.
683 A wildcard citation \citation{*} tells Pybtex to format the
685 bibliography for all entries from all data files specified by
686 all \bibdata commands.
687 2. Pybtex executes the style program in the .bst file specified by the
689 \bibstyle command in the .aux file. As a result, a .bbl file con‐
690 taining the resulting formatted bibliography is created.
691 A .bst style file is a program in a domain-specific stack-based lan‐
693 guage. A typical piece of the .bst code looks like this:
694 FUNCTION {format.bvolume}
696 { volume empty$
697 { "" }
698 { "volume" volume tie.or.space.connect
699 series empty$
700 'skip$
701 { " of " * series emphasize * }
702 if$
703 "volume and number" number either.or.check
704 }
705 if$
706 }
707 The code in a .bst file contains the complete step-by-step instruc‐
709 tions on how to create the formatted bibliography from the given
710 bibliography data and citation keys. For example, a READ command
711 tells Pybtex to read the bibliography data from all files specified
712 by \bibdata commands in the .aux file, an ITERATE command tells Pyb‐
713 tex to execute a piece of code for each citation key specified by
714 \citation commands, and so on. The built-in write$ function tells
715 Pybtex to write the given string into the resulting .bbl file. Pyb‐
716 tex implements all these commands and built-in functions and simply
717 executes the .bst program step by step.
718 A complete reference of the .bst language can be found in the BibTeX
720 hacking guide by Oren Patashnik. It is available by running texdoc
721 btxhak in most TeX distributions.
722 Python engine
724 The Python engine is enabled by running pybtex with the -l python op‐
725 tion.
726 Differences from the BibTeX engine
728 • Formatting styles are written in Python instead of the .bst language.
729 • Formatting styles are not tied to LaTeX and do not use hardcoded La‐
731 TeX markup. Instead of that they produce format-agnostic
732 pybtex.richtext.Text objects that can be converted to any markup for‐
733 mat (LaTeX, Markdown, HTML, etc.).
734 • Name formatting, label formatting, and sorting styles are defined
736 separately from the main style.
737 How it works
739 When you type pybtex -l python mydocument, this things happen:
740 1. Pybtex reads the file mydocument.aux in the current directory and
742 extracts the name of the the bibliography style, the list of bibli‐
743 ography data files and the list of citation keys. This step is ex‐
744 actly the same as with the BibTeX engine.
745 2. Pybtex reads the biliography data from all data files specified in
747 the .aux file into a single BibliographyData object.
748 3. Then the formatting style is loaded. The formatting style is a
750 Python class with a format_bibliography() method. Pybtex passes the
751 bibliography data (a BibliographyData object) and the list of cita‐
752 tion keys to format_bibliography().
753 4. The formatting style formats each of the requested bibliography en‐
755 tries in a style-specific way.
756 When it comes to formatting names, a name formatting style is loaded
758 and used. A name formatting style is also a Python class with a spe‐
759 cific interface. Similarly, a label formatting style is used to
760 format entry labels, and a sorting style is used to sort the result‐
761 ing style. Each formatting style has a default name style, a de‐
762 fault label style and a default sorting style. The defaults can be
763 overridden with options passed to the main style class.
764 Each formatted entry is put into a FormattedEntry object which is
766 just a container for the formatted label, the formatted entry text
767 (a pybtex.richtext.Text object) and the entry key. The reason that
768 the label, the key and the main text are stored separately is to
769 give the output backend more flexibility when converting the Format‐
770 tedEntry object to the actual markup. For example, the HTML backend
771 may want to format the bibliography as a definition list, the LaTeX
772 backend would use \bibitem[label]{key} text constructs, etc.
773 Formatted entries are put into a FormattedBibliography object—it
775 simply contains a list of FormattedEntry objects and some additional
776 metadata.
777 5. The resulting FormattedBibliography is passed to the output backend.
779 The default backend is LaTeX. It can be changed with the pybtex
780 --output-backend option. The output backend converts the formatted
781 bibliography to the specific markup format and writes it to the out‐
782 put file.
783 Python API
785 The base interface
786 Both the Python engine and the BibTeX engine use the same interface de‐
787 fined in pybtex.Engine.
788 pybtex.Engine has a handful of methods but most of them are just conve‐
790 nience wrappers for Engine.format_from_files() that does the actual
791 job.
792 class pybtex.Engine
794 make_bibliography(aux_filename, style=None, output_encod‐
796 ing=None, bib_format=None, **kwargs)
797 Read the given .aux file and produce a formatted bibliog‐
798 raphy using format_from_files().
799 Parameters
801 style – If not None, use this style instead of
802 specified in the .aux file.
803 format_from_string(bib_string, *args, **kwargs)
805 Parse the bigliography data from the given string and
806 produce a formated bibliography using
807 format_from_files().
808 This is a convenience method that calls
810 format_from_strings() with a single string.
811 format_from_strings(bib_strings, *args, **kwargs)
813 Parse the bigliography data from the given strings and
814 produce a formated bibliography.
815 This is a convenience method that wraps each string into
817 a StringIO, then calls format_from_files().
818 format_from_file(filename, *args, **kwargs)
820 Read the bigliography data from the given file and pro‐
821 duce a formated bibliography.
822 This is a convenience method that calls
824 format_from_files() with a single file. All extra argu‐
825 ments are passed to format_from_files().
826 format_from_files(**kwargs)
828 Read the bigliography data from the given files and pro‐
829 duce a formated bibliography.
830 This is an abstract method overridden by both
832 pybtex.PybtexEngine and pybtex.bibtex.BibTeXEngine.
833 The BibTeXEngine class
835 The BibTeX engine lives in the pybtex.bibtex module. The public inter‐
836 face consists of the BibTeXEngine class and a couple of convenience
837 functions.
838 class pybtex.bibtex.BibTeXEngine
840 The Python fomatting engine.
841 See pybtex.Engine for inherited methods.
843 format_from_files(bib_files_or_filenames, style, cita‐
845 tions=['*'], bib_format=None, bib_encoding=None, output_encod‐
846 ing=None, bst_encoding=None, min_crossrefs=2, output_file‐
847 name=None, add_output_suffix=False, **kwargs)
848 Read the bigliography data from the given files and pro‐
849 duce a formated bibliography.
850 Parameters
852 • bib_files_or_filenames – A list of file names or
854 file objects.
855 • style – The name of the formatting style.
857 • citations – A list of citation keys.
859 • bib_format – The name of the bibliography for‐
861 mat. The default format is bibtex.
862 • bib_encoding – Encoding of bibliography files.
864 • output_encoding – Encoding that will be used by
866 the output backend.
867 • bst_encoding – Encoding of the .bst file.
869 • min_crossrefs – Include cross-referenced entries
871 after this many crossrefs. See BibTeX manual for
872 details.
873 • output_filename – If None, the result will be
875 returned as a string. Else, the result will be
876 written to the specified file.
877 • add_output_suffix – Append a .bbl suffix to the
879 output file name.
880 pybtex.bibtex.make_bibliography(*args, **kwargs)
882 A convenience function that calls BibTeXEngine.make_bibliogra‐
883 phy().
884 pybtex.bibtex.format_from_string(*args, **kwargs)
886 A convenience function that calls BibTeXEngine.for‐
887 mat_from_string().
888 pybtex.bibtex.format_from_strings(*args, **kwargs)
890 A convenience function that calls BibTeXEngine.for‐
891 mat_from_strings().
892 pybtex.bibtex.format_from_file(*args, **kwargs)
894 A convenience function that calls BibTeXEngine.for‐
895 mat_from_file().
896 pybtex.bibtex.format_from_files(*args, **kwargs)
898 A convenience function that calls
899 BibTeXEngine.format_from_files().
900 The PybtexEngine class
902 The Python engine resides in the pybtex module and uses an interface
903 similar to the BibTeX engine. There is the PybtexEngine class and some
904 convenience functions.
905 class pybtex.PybtexEngine
907 The Python fomatting engine.
908 See pybtex.Engine for inherited methods.
910 format_from_files(bib_files_or_filenames, style, cita‐
912 tions=['*'], bib_format=None, bib_encoding=None, output_back‐
913 end=None, output_encoding=None, min_crossrefs=2, output_file‐
914 name=None, add_output_suffix=False, **kwargs)
915 Read the bigliography data from the given files and pro‐
916 duce a formated bibliography.
917 Parameters
919 • bib_files_or_filenames – A list of file names or
921 file objects.
922 • style – The name of the formatting style.
924 • citations – A list of citation keys.
926 • bib_format – The name of the bibliography for‐
928 mat. The default format is bibtex.
929 • bib_encoding – Encoding of bibliography files.
931 • output_backend – Which output backend to use.
933 The default is latex.
934 • output_encoding – Encoding that will be used by
936 the output backend.
937 • bst_encoding – Encoding of the .bst file.
939 • min_crossrefs – Include cross-referenced entries
941 after this many crossrefs. See BibTeX manual for
942 details.
943 • output_filename – If None, the result will be
945 returned as a string. Else, the result will be
946 written to the specified file.
947 • add_output_suffix – Append default suffix to the
949 output file name (.bbl for LaTeX, .html for
950 HTML, etc.).
951 pybtex.make_bibliography(*args, **kwargs)
953 A convenience function that calls PybtexEngine.make_bibliogra‐
954 phy().
955 pybtex.format_from_string(*args, **kwargs)
957 A convenience function that calls PybtexEngine.for‐
958 mat_from_string().
959 pybtex.format_from_strings(*args, **kwargs)
961 A convenience function that calls PybtexEngine.for‐
962 mat_from_strings().
963 pybtex.format_from_file(*args, **kwargs)
965 A convenience function that calls PybtexEngine.for‐
966 mat_from_file().
967 pybtex.format_from_files(*args, **kwargs)
969 A convenience function that calls
970 PybtexEngine.format_from_files().
971 Designing styles
973 • Rich text
974 • Rich text classes
976 • Style API
978 • Template language
980 Rich text
982 Pybtex has a set of classes for working with formatted text and produc‐
983 ing formatted output. A piece of formatted text in Pybtex is repre‐
984 sented by a Text object. A Text is basically a container that holds a
985 list of
986 • plain text parts, represented by String objects,
988 • formatted parts, represented by Tag and HRef objects.
990 The basic workflow is:
992 1. Construct a Text object.
994 2. Render it as LaTeX, HTML or other markup.
996 >>> from pybtex.richtext import Text, Tag
998 >>> text = Text('How to be ', Tag('em', 'a cat'), '.')
999 >>> print(text.render_as('html'))
1000 How to be <em>a cat</em>.
1001 >>> print(text.render_as('latex'))
1002 How to be \emph{a cat}.
1003 Rich text classes
1005 There are several rich text classes in Pybtex:
1006 • Text
1008 • String
1010 • Tag
1012 • HRef
1014 • Protected
1016 Text is the top level container that may contain String, Tag, and HRef
1018 objects. When a Text object is rendered into markup, it renders all of
1019 its child objects, then concatenates the result.
1020 String is just a wrapper for a single Python string.
1022 Tag and HRef are also containers that may contain other String, Tag,
1024 and HRef objects. This makes nested formatting possible. For example,
1025 this stupidly formatted text:
1026 Comprehensive TeX Archive Network is comprehensive.
1027 is represented by this object tree:
1029 >>> text = Text(
1031 ... HRef('https://ctan.org/', Tag('em', 'Comprehensive'), ' TeX Archive Network'),
1032 ... ' is ',
1033 ... Tag('em', 'comprehensive'),
1034 ... '.',
1035 ... )
1036 >>> print(text.render_as('html'))
1037 <a href="https://ctan.org/"><em>Comprehensive</em> TeX Archive Network</a> is <em>comprehensive</em>.
1038 Protected represents a “protected” piece of text, something like
1040 {braced text} in BibTeX. It is not affected by case-changing opera‐
1041 tions, like Text.upper() or Text.lower(), and is not splittable by
1042 Text.split().
1043 All rich text classes share the same API which is more or less similar
1045 to plain Python strings.
1046 Like Python strings, rich text objects are supposed to be immutable.
1048 Methods like Text.append() or Text.upper() return a new Text object in‐
1049 stead of modifying the data in place. Attempting to modify the con‐
1050 tents of an existing Text object is not supported and may lead to weird
1051 results.
1052 Here we document the methods of the Text class. The other classes have
1054 the same methods.
1055 class pybtex.richtext.Text(*parts)
1057 The Text class is the top level container that may contain
1058 String, Tag or HRef objects.
1059 __init__(*parts)
1061 Create a text object consisting of one or more parts.
1062 Empty parts are ignored:
1064 >>> Text() == Text('') == Text('', '', '')
1066 True
1067 >>> Text('Word', '') == Text('Word')
1068 True
1069 Text() objects are unpacked and their children are in‐
1071 cluded directly:
1072 >>> Text(Text('Multi', ' '), Tag('em', 'part'), Text(' ', Text('text!')))
1074 Text('Multi ', Tag('em', 'part'), ' text!')
1075 >>> Tag('strong', Text('Multi', ' '), Tag('em', 'part'), Text(' ', 'text!'))
1076 Tag('strong', 'Multi ', Tag('em', 'part'), ' text!')
1077 Similar objects are merged together:
1079 >>> Text('Multi', Tag('em', 'part'), Text(Tag('em', ' ', 'text!')))
1081 Text('Multi', Tag('em', 'part text!'))
1082 >>> Text('Please ', HRef('/', 'click'), HRef('/', ' here'), '.')
1083 Text('Please ', HRef('/', 'click here'), '.')
1084 __eq__(other)
1086 Rich text objects support equality comparison:
1087 >>> Text('Cat') == Text('cat')
1089 False
1090 >>> Text('Cat') == Text('Cat')
1091 True
1092 __len__()
1094 len(text) returns the number of characters in the text,
1095 ignoring the markup:
1096 >>> len(Text('Long cat'))
1098 8
1099 >>> len(Text(Tag('em', 'Long'), ' cat'))
1100 8
1101 >>> len(Text(HRef('http://example.com/', 'Long'), ' cat'))
1102 8
1103 __contains__(item)
1105 value in text returns True if any part of the text con‐
1106 tains the substring value:
1107 >>> 'Long cat' in Text('Long cat!')
1109 True
1110 Substrings splitted across multiple text parts are not
1112 matched:
1113 >>> 'Long cat' in Text(Tag('em', 'Long'), 'cat!')
1115 False
1116 __getitem__(key)
1118 Slicing and extracting characters works like with regular
1119 strings, formatting is preserved.
1120 >>> Text('Longcat is ', Tag('em', 'looooooong!'))[:15]
1122 Text('Longcat is ', Tag('em', 'looo'))
1123 >>> Text('Longcat is ', Tag('em', 'looooooong!'))[-1]
1124 Text(Tag('em', '!'))
1125 __add__(other)
1127 Concatenate this Text with another Text or string.
1128 >>> Text('Longcat is ') + Tag('em', 'long')
1130 Text('Longcat is ', Tag('em', 'long'))
1131 add_period(period='.')
1133 Add a period to the end of text, if the last character is
1134 not “.”, “!” or “?”.
1135 >>> text = Text("That's all, folks")
1137 >>> print(six.text_type(text.add_period()))
1138 That's all, folks.
1139 >>> text = Text("That's all, folks!")
1141 >>> print(six.text_type(text.add_period()))
1142 That's all, folks!
1143 append(text)
1145 Append text to the end of this text.
1146 For Tags, HRefs, etc. the appended text is placed inside
1148 the tag.
1149 >>> text = Tag('strong', 'Chuck Norris')
1151 >>> print((text + ' wins!').render_as('html'))
1152 <strong>Chuck Norris</strong> wins!
1153 >>> print(text.append(' wins!').render_as('html'))
1154 <strong>Chuck Norris wins!</strong>
1155 capfirst()
1157 Capitalize the first letter of the text.
1158 >>> Text(Tag('em', 'long Cat')).capfirst()
1160 Text(Tag('em', 'Long Cat'))
1161 capitalize()
1163 Capitalize the first letter of the text and lowercase the
1164 rest.
1165 >>> Text(Tag('em', 'LONG CAT')).capitalize()
1167 Text(Tag('em', 'Long cat'))
1168 endswith(suffix)
1170 Return True if the text ends with the given suffix.
1171 >>> Text('Longcat!').endswith('cat!')
1173 True
1174 Suffixes split across multiple parts are not matched:
1176 >>> Text('Long', Tag('em', 'cat'), '!').endswith('cat!')
1178 False
1179 isalpha()
1181 Return True if all characters in the string are alpha‐
1182 betic and there is at least one character, False other‐
1183 wise.
1184 join(parts)
1186 Join a list using this text (like string.join)
1187 >>> letters = ['a', 'b', 'c']
1189 >>> print(six.text_type(String('-').join(letters)))
1190 a-b-c
1191 >>> print(six.text_type(String('-').join(iter(letters))))
1192 a-b-c
1193 lower()
1195 Convert rich text to lowercase.
1196 >>> Text(Tag('em', 'Long cat')).lower()
1198 Text(Tag('em', 'long cat'))
1199 render(backend)
1201 Render this Text into markup.
1202 Parameters
1204 backend – The formatting backend (an instance of
1205 pybtex.backends.BaseBackend).
1206 render_as(backend_name)
1208 Render this Text into markup. This is a wrapper method
1209 that loads a formatting backend plugin and calls
1210 Text.render().
1211 >>> text = Text('Longcat is ', Tag('em', 'looooooong'), '!')
1213 >>> print(text.render_as('html'))
1214 Longcat is <em>looooooong</em>!
1215 >>> print(text.render_as('latex'))
1216 Longcat is \emph{looooooong}!
1217 >>> print(text.render_as('text'))
1218 Longcat is looooooong!
1219 Parameters
1221 backend_name – The name of the output backend
1222 (like "latex" or "html").
1223 split(sep=None, keep_empty_parts=None)
1225 >>> Text('a + b').split()
1227 [Text('a'), Text('+'), Text('b')]
1228 >>> Text('a, b').split(', ')
1230 [Text('a'), Text('b')]
1231 startswith(prefix)
1233 Return True if the text starts with the given prefix.
1234 >>> Text('Longcat!').startswith('Longcat')
1236 True
1237 Prefixes split across multiple parts are not matched:
1239 >>> Text(Tag('em', 'Long'), 'cat!').startswith('Longcat')
1241 False
1242 upper()
1244 Convert rich text to uppsercase.
1245 >>> Text(Tag('em', 'Long cat')).upper()
1247 Text(Tag('em', 'LONG CAT'))
1248 class pybtex.richtext.String(*parts)
1250 A String is a wrapper for a plain Python string.
1251 >>> from pybtex.richtext import String
1253 >>> print(String('Crime & Punishment').render_as('text'))
1254 Crime & Punishment
1255 >>> print(String('Crime & Punishment').render_as('html'))
1256 Crime & Punishment
1257 String supports the same methods as Text.
1259 class pybtex.richtext.Tag(name, *args)
1261 A Tag represents something like an HTML tag or a LaTeX format‐
1262 ting command:
1263 >>> from pybtex.richtext import Tag
1265 >>> tag = Tag('em', 'The TeXbook')
1266 >>> print(tag.render_as('html'))
1267 <em>The TeXbook</em>
1268 >>> print(tag.render_as('latex'))
1269 \emph{The TeXbook}
1270 Tag supports the same methods as Text.
1272 class pybtex.richtext.HRef(url, *args)
1274 A HRef represends a hyperlink:
1275 >>> from pybtex.richtext import Tag
1277 >>> href = HRef('http://ctan.org/', 'CTAN')
1278 >>> print(href.render_as('html'))
1279 <a href="http://ctan.org/">CTAN</a>
1280 >>> print(href.render_as('latex'))
1281 \href{http://ctan.org/}{CTAN}
1282 >>> href = HRef(String('http://ctan.org/'), String('http://ctan.org/'))
1284 >>> print(href.render_as('latex'))
1285 \url{http://ctan.org/}
1286 HRef supports the same methods as Text.
1288 class pybtex.richtext.Protected(*args)
1290 A Protected represents a “protected” piece of text.
1291 • Protected.lower(), Protected.upper(), Protected.capitalize(),
1293 and Protected.capitalize() are no-ops and just return the
1294 Protected object itself.
1295 • Protected.split() never splits the text. It always returns a
1297 one-element list containing the Protected object itself.
1298 • In LaTeX output, Protected is {surrounded by braces}. HTML
1300 and plain text backends just output the text as-is.
1301 >>> from pybtex.richtext import Protected
1303 >>> text = Protected('The CTAN archive')
1304 >>> text.lower()
1305 Protected('The CTAN archive')
1306 >>> text.split()
1307 [Protected('The CTAN archive')]
1308 >>> print(text.render_as('latex'))
1309 {The CTAN archive}
1310 >>> print(text.render_as('html'))
1311 <span class="bibtex-protected">The CTAN archive</span>
1312 New in version 0.20.
1314 class pybtex.richtext.Symbol(name)
1317 A special symbol. This class is rarely used and may be removed
1318 in future versions.
1319 Examples of special symbols are non-breaking spaces and dashes.
1321 Symbol supports the same methods as Text.
1323 Style API
1325 A formatting style in Pybtex is a class inherited from
1326 pybtex.style.formatting.BaseStyle.
1327 class pybtex.style.formatting.BaseStyle(label_style=None,
1329 name_style=None, sorting_style=None, abbreviate_names=False, min_cross‐
1330 refs=2, **kwargs)
1331 The base class for pythonic formatting styles.
1332 format_bibliography(bib_data, citations=None)
1334 Format bibliography entries with the given keys and re‐
1335 turn a FormattedBibliography object.
1336 Parameters
1338 • bib_data – A pybtex.database.BibliographyData
1340 object.
1341 • citations – A list of citation keys.
1343 Pybtex loads the style class as a plugin, instantiates it with proper
1345 parameters and calls the format_bibliography() method that does the ac‐
1346 tual formatting job. The default implementation of
1347 format_bibliography() calls a format_<type>() method for each bibliog‐
1348 raphy entry, where <type> is the entry type, in lowercase. For example,
1349 to format an entry of type book, the format_book() method is called.
1350 The method must return a Text object. Style classes are supposed to
1351 implement format_<type>() methods for all entry types they support. If
1352 a formatting method is not found for some entry, Pybtex complains about
1353 unsupported entry type.
1354 An example minimalistic style:
1356 from pybtex.style.formatting import BaseStyle
1358 from pybtex.richtext import Text, Tag
1359 class MyStyle(BaseStyle):
1361 def format_article(self, entry):
1362 return Text('Article ', Tag('em', entry.fields['title']))
1363 Template language
1365 Manually creating Text objects may be tedious. Pybtex has a small tem‐
1366 plate language to simplify common formatting tasks, like joining words
1367 with spaces, adding commas and periods, or handling missing fields.
1368 The template language is is not very documented for now, so you should
1370 look at the code in the pybtex.style.template module and the existing
1371 styles.
1372 An example formatting style using template language:
1374 from pybtex.style.formatting import BaseStyle, toplevel
1376 from pybtex.style.template import field, join, optional
1377 class MyStyle(BaseStyle):
1379 def format_article(self, entry):
1380 if entry.fields['volume']:
1381 volume_and_pages = join [field('volume'), optional [':', pages]]
1382 else:
1383 volume_and_pages = words ['pages', optional [pages]]
1384 template = toplevel [
1385 self.format_names('author'),
1386 sentence [field('title')],
1387 sentence [
1388 tag('emph') [field('journal')], volume_and_pages, date],
1389 ]
1390 return template.format_data(entry)
1391 Extending Pybtex with plugins
1393 • Entry points
1394 • pybtex.database.input
1396 • pybtex.database.output
1398 • pybtex.backends
1400 • pybtex.style.formatting
1402 • pybtex.style.labels
1404 • pybtex.style.names
1406 • pybtex.style.sorting
1408 • Registering plugins
1410 • Example plugins
1412 Pybtex uses plugins for bibliography data formats, output markup for‐
1414 mats and bibliography formatting styles. This allows to add new formats
1415 or styles to Pybtex withoud modifying Pybtex itself.
1416 The plugins are based on Setuptools’ entry points.
1418 Entry points
1420 Here is the list of entry points supported by Pybtex.
1421 pybtex.database.input
1423 This entry point is used for bibliography parsers. Must point to a
1424 subclass of pybtex.database.input.BaseParser.
1425 There is also an additional entry point called pybtex.database.out‐
1427 put.suffixes. It is used for registering bibliography formats for spe‐
1428 cific file suffixes (like BibTeX for .bib files).
1429 For example, a JSON input plugin could use these entry points:
1431 [pybtex.database.input]
1433 json = pybtexjson:JSONParser
1434 [pybtex.database.input.suffixes]
1436 .json = pybtexjson:JSONParser
1437 pybtex.database.output
1439 This entry poing is used for bibliography writers. Must point to a
1440 subclass of pybtex.database.output.BaseWriter.
1441 There is also an additional entry point called pybtex.database.out‐
1443 put.suffixes. It is used for registering default plugins for specific
1444 file suffixes in the same way as pybtex.database.input.suffixes de‐
1445 scribed above.
1446 pybtex.backends
1448 This entry point is for adding new output markup formats for Pythonic
1449 bibliography styles. The built-in plugins are latex, html, markdown,
1450 and plaintext. Must point to a pybtex.backends.BaseBackend subclass.
1451 pybtex.style.formatting
1453 This is the entry point for Pythonic bibliography styles. Must point to
1454 a pybtex.style.formatting.BaseStyle subclass.
1455 pybtex.style.labels
1457 Label styles for Pythonic bibliography styles.
1458 pybtex.style.names
1460 Name styles for Pythonic bibliography styles.
1461 pybtex.style.sorting
1463 Sorting styles for Pythonic bibliography styles.
1464 Registering plugins
1466 See Setuptools’ documentation.
1467 Example plugins
1469 An example project directory with two simple plugins and a setup.py
1470 file can be found in the examples/sample_plugins subdirectory.
1471
1473 Version 0.24.0
1474 (released on January 17, 2021)
1475 This is the last version that supports Python 2. The next version will
1477 require Python 3.6 or above.
1478 • Added support for sup and sub tags to LaTeX and Markdown backends.
1480 • Added support for @online entries and the urldate field.
1482 • Restored compatibility with Python 2.
1484 • Fixed tests on Windows.
1486 • Fixed bugs in the example plugin.
1488 • Fixed bad get_default_encoding() call.
1490 Thanks to Matthias Troffaes for his contributions!
1492 Version 0.23.0
1494 (released on October 12, 2020)
1495 • Reimplemented OrderedCaseInsensitiveDict using
1497 collections.OrderedDict (so it has a __delitem__).
1498 • unsrt.py now supports type when formatting phdthesis.
1500 • Added from_string() to pybtex.database.BibliographyData.
1502 • Added from_string() and to_string() to pybtex.database.Entry.
1504 • Added indentation to __repr__ in pybtex.database.BibliographyData and
1506 pybtex.database.Entry.
1507 • Preserve order in pybtex.utils.OrderedCaseInsensitiveDict.__repr__().
1509 • Fixed entries with duplicate keys being removed during sorting.
1511 • Fixed handling of duplicate person fields
1513 • Use ElementTree instead of the deprecated cElementTree.
1515 • Import base classes from collections.abc instead of collections.
1517 • Use __iter__ instead of deprecated Element.getchildren().
1519 Thanks to David Chiang, Jerry James, Jannik Schürg, Nathaniel Starkman,
1521 and Matthias Troffaes for their fixes and improvements!
1522 Version 0.22.2
1524 (released on January 17, 2019)
1525 • Fixed compatibility with Python 2 and older versions of Python 3.
1527 Version 0.22.1
1529 (released on January 16, 2019)
1530 • Fixed non-working --backend option with pybtex -l python.
1532 Version 0.22.0
1534 (released on November 18, 2018)
1535 • Fixed handling of duplicate fields in .bib biles. Thanks, Jannik
1537 Schürg!
1538 • BibTeX parser is now up to 10% faster on some files. Thanks, Fabrice
1540 Benhamouda!
1541 • Fixed parsing of names with \~ characters.
1543 • Fixed formatting proceedings without an editor field in unsrt.py.
1545 • In case of too many braces in a BibTeX string, PybtexSyntaxError is
1547 now raised instead of RecursionError.
1548 • Dropped 2to3, made the code compatible with both Python 2 and 3 with
1550 Six.
1551 • Moved tests outside of the pybtex package.
1553 • Fixed searching in docs with recent versions of Sphinx.
1555 • API: renamed bibtex.BibTeXEntryIterator to bibtex.LowLevelParser for
1557 clarity.
1558 • API: removed confusing usage of Person.text in tempate.names.
1560 • API: Entry.fields does not automagically look for cross-referenced
1562 entries anymore.
1563 Version 0.21
1565 (released on January 20, 2017)
1566 • BibTeX writer now uses latexcodec to encode characters that are not
1568 directly supported by the output encoding. Thanks, Hong Xu!
1569 • HTML backend: {braced stings} are now wrapped with <span class="bib‐
1571 tex-protected"> to enable custom CSS styling.
1572 • unsrt.py: DOI, PubMed and Arxiv links now use HTTPS instead of HTTP.
1574 • unsrt.py: URLs with percent characters are now formatted correctly.
1576 • unsrt.py: short page / volume / chapter numbers are now joined with a
1578 non-breaking space, like in BibTeX.
1579 • unsrt.py: inbook now uses the editor field if the author field is
1581 missing, like in BibTeX.
1582 • unsrt.py: the words “volume” and “pages” in the beginning of the sen‐
1584 tence are now capitalized, like in BibTeX.
1585 • unsrt.py: removed unnecessary period between the book title and the
1587 comma in inbook.
1588 Version 0.20.1
1590 (released on March 17, 2016)
1591 • LaTeX backend: fix encoding tilde ("~") characters with newer ver‐
1593 sions of latexcodec.
1594 • Fix splitting names with escaped space ("\ ") characters.
1596 Version 0.20
1598 (released on March 10, 2016)
1599 • YAML reader and writer now preserve the order of bibliography en‐
1601 tries.
1602 • Improved URL formatting in pythonic styles.
1604 • Built-in pythonic styles now support the ISBN field.
1606 • Pythonic styles now treat LaTeX braces correctly:
1608 • case conversion does not affect {braced substrings},
1610 • braces are stripped from non-LaTeX output: "{P}ython" becomes
1612 "Python".
1613 • Pythonic styles now use latexcodec to decode LaTeX markup. For exam‐
1615 ple, "Schr\"odinger" is now correctly rendered as "Schrödinger" in
1616 HTML or plain text.
1617 Thanks to Hong Xu for his contributions!
1619 Version 0.19
1621 (released on October 26, 2015)
1622 • Added Markdown output format (contributed by Jorrit Wronski).
1624 • Incorrectly formatted author and editor names now result in warnings
1626 instead of errors, unless --strict mode is enabled.
1627 • Fixed HTML escaping.
1629 • Fixed parsing nested .aux files.
1631 • Fixed splitting names separated by non-lowercase " and ".
1633 • Fixed line numbers in error messages when parsing strings with
1635 DOS/Windows line breaks.
1636 • Fixed compatibility with BibTeX when parsing certain weird “von”
1638 names.
1639 • Removed excessive trailing newline from .bib output.
1641 • Text wrapping now works exactly as in BibTeX.
1643 • Added new API for reading and writing bibliography data.
1645 • Pythonic styles: reworked and extended the rich text API.
1647 • Pythonic styles: added strong, i, b, tt tags, renamed the old emph
1649 tag to em.
1650 • Pythonic styles: the author_year_title style now returns "" instead
1652 of None (fixes unorderable types error in Python 3).
1653 • Ported the documentation to Sphinx.
1655 Thanks to Jorrit Wronski and Matthias Troffaes for their fixes and im‐
1657 provements!
1658 Version 0.18
1660 (released on July 6, 2014)
1661 • Pybtex is now fully case-insensitive (like BibTeX). As a consequence,
1663 IEEEtran styles now work correctly.
1664 • Added --preserve-case option to pybtex-convert (default behavior is
1666 to converted all identifiers to lower case).
1667 • An error is reported if two citations have the same key but different
1669 case, like in BibTeX. (Example: ddt1999 and DDT1999).
1670 • Fixed parsing unused bibliography entries with strings containing @
1672 characters.
1673 • entry.max$ constant is now set to 250, global.max$ is set to 20000,
1675 like in BibTeX.
1676 • Added --strict option to pybtex-convert and pybtex-format (turns
1678 warning into errors).
1679 • Strict mode is now enabled by default when using pybtex as a library
1681 (exceptions are raised on all errors instead of just printing warn‐
1682 ings to stderr).
1683 Non-strict error handling is still enabled when using pybtex from the
1685 command line, for compatibility with BibTeX. Use --strict option if
1686 you don’t like this.
1687 • Added missing pybtex-format manpage.
1689 Version 0.17
1691 (released on March 10, 2014)
1692 • Added pybtex-format utility for formatting bibliography files as
1694 HTML, LaTeX, and other supported human-readable formats.
1695 • Added --strict command line option to pybtex (all warnings become er‐
1697 rors).
1698 • Added alpha label style, and alpha and unsrtalpha formatting styles.
1700 • Added support for url, eprint, doi, and pubmed fields in unsrt style.
1702 • Names with hyphens are now abbreviated correctly (“Jean-Baptiste” be‐
1704 comes “J.-B.”).
1705 • width$ now uses cmr10 font metrics, like in BibTeX. Non-latin charac‐
1707 ters are also supported.
1708 • Pythonic style engine now supports @preamble commands.
1710 • Warning on missing fields are now more human-readable.
1712 • When writing BibTeX files, put entry key on the same line with entry
1714 type. Fixes warnings in Jabref.
1715 • When using multiple .bib files, macros defined in earlier files are
1717 available in subsequent ones (like in BibTeX).
1718 • Fixed parsing .bst files with lines consisting of a single % charac‐
1720 ter.
1721 • Fixed sorting entries without author in author_year_title sorting
1723 style.
1724 • Fixed broken CaseInsensitiveDict.get().
1726 • CaseInsensitiveDict is now pickleable.
1728 • Added support for registering plugins at runtime with pyb‐
1730 tex.plugin.register_plugin() - useful for using pybtex as a library.
1731 Many thanks to Matthias C. M. Troffaes for his numerous fixes and im‐
1733 provements!
1734 Version 0.16
1736 (released on March 17, 2012)
1737 • BibTeX .bib and .bst parsers were completely rewritten. They are now
1739 much faster and more BibTeX-compatible.
1740 • Syntax errors and undefined strings in .bib files now result in warn‐
1742 ings instead of errors, like in BibTeX.
1743 • Unused entries in .bib files are now skipped, like in BibTeX.
1745 • The case of entry keys is now preserved (in previous versions they
1747 were converted to lowercase).
1748 • Pythonic style engine now supports sorting.
1750 • Pythonic style engine: fixed nested optional() blocks.
1752 • Fixed parsing of some names with a Last part but no von part.
1754 • Fixed processing of brace-level-one “special characters” in purify$
1756 BibTeX built-in function.
1757 • Added proper error messages on encoding errors in .bib files.
1759 • The default encoding is now UTF-8 on all platforms.
1761 • pybtex-convert now preserves the order of entries in BibTeX and Bib‐
1763 TeXML files.
1764 The following changes were contributed by Matthias C. M. Troffaes:
1766 • Fixed first_of behavior when non-empty child is followed by a child
1768 that has a missing field.
1769 • Fixed crossref lookups when key is not lower case.
1771 • Completed unsrt and plain python styles: they now contain all entry
1773 types.
1774 • Added doctree backend for rendering into a tree of docutils nodes.
1776 • Added support for non-string backends.
1778 Version 0.15
1780 (released on February 1, 2011)
1781 • Changed license from GPL-3 to MIT.
1783 • Added support for setuptools plugins.
1785 • BibTeX parser: fixed whitespace normalization in concatenated
1787 strings.
1788 • BibTeX parser: when parsing multiple BibTeX files, macros defined in
1790 earlier files are now available to all subsequent files, like in Bib‐
1791 TeX.
1792 • BibTeX .bst interpreter now prints warnings on missing entries, like
1794 BibTeX, instead of raising a KeyError.
1795 • call.type$ BibTeX built-in function now uses default.entry for un‐
1797 known entry types, like in BibTeX.
1798 • substring$ now accepts start=0 and returns an empty string.
1800 • change.case$: fixed incorrect formatting of strings starting with
1802 special characters with "t" format.
1803 • Fixed abbreviation of names starting with special characters or
1805 non-alphabetic characters.
1806 • Fixed incorrect entry order and duplicated entries with \nocite{*}.
1808 • Added more detailed error messages for already defined variables in
1810 .bst files.
1811 Version 0.14.1
1813 (released on September 30, 2010)
1814 • Added missing custom_fixers directory to the tarball — needed only
1816 for converting the sources to Python 3.
1817 Version 0.14
1819 (released on September 20, 2010)
1820 • BibTeX writer: fixed quoting " (double quote) characters.
1822 • BibTeX parser now produces human-readable error messages on unread
1824 macros.
1825 • Added error messages on missing data in .aux files.
1827 • Improved performance on very long name lists.
1829 • Added support for Python 3.
1831 Version 0.13.2
1833 (released on February 26, 2010)
1834 • BibTeX parser: fixed a bug with parsing strings containing braces,
1836 like "Error in {DNA}".
1837 Version 0.13.1
1839 (released on February 18, 2010)
1840 • Fixed ImportError: No module named kpathsea errors. One of the source
1842 files was missing from pybtex-0.13.tar.bz2 for some strange reason.
1843 Sorry about that. ;)
1844 Version 0.13
1846 (released on February 14, 2010)
1847 • Implemented --min-crossrefs option.
1849 • All command line options of the original BibTeX are not supported.
1851 • Pybtex now respects BSTINPUTS, BIBINPUTS and TEXMFOUTPUT environment
1853 variables.
1854 • BibTeX bibliography parser now strips excessive whitespace from
1856 fields, like BibTeX does.
1857 Version 0.12
1859 (released on November 21, 2009)
1860 • Pybtex now works correctly with \input{filename} in LaTeX files.
1862 • Added a proper change.case$ BibTeX function instead of a stub.
1864 • Added -e/--encoding command line option.
1866 • Fixed non-working --bibtex-encoding option.
1868 • Added proper error messages on missing plugins, file IO errors, some
1870 BibTeX interpreter errors, etc.
1871 • Fallback to backslash-encoding when printing messages to the console
1873 - to make them printable regardless of the locale.
1874 Version 0.11
1876 (released on September 7, 2009)
1877 • Made text.lentgh$ and text.prefix$ BibTeX built-in functions treat
1879 braces and TeX special characters properly (like the original BibTeX
1880 functions do).
1881 • Changed purify$ to replace ties and hyphens by spaces.
1883 • Fixed a bug in substring$ with negative start values.
1885 • Fixed .bst file grammar to allow underscores in identifiers.
1887 • BibTeX name parser: ties are now treated as whitespace when splitting
1889 name parts.
1890 • Implemented BibTeX-like text wrapping. The resulting .bbl output
1892 should now be byte-for-byte identical to that of BibTeX in most
1893 cases.
1894 Version 0.10
1896 (released on August 24, 2009)
1897 • Added support for multiple bibliography databases.
1899 • Pythonic bibliography formatter: added helper functions to simplify
1901 writing BibTeX-like name formatting styles in Python. Added a tool
1902 for automatic conversion of BibTeX {ll}{, ff}-like patterns into
1903 Python.
1904 • BibTeX parser: added missing characters to the caracter set of the
1906 valid identifiers.
1907 • BibTeX parser: a comma is now allowed between the last field and the
1909 closing brace.
1910 • BibTeX name parser: when splitting name parts into words, whitespace
1912 at brace level > 0 is now ignored.
1913 • BibTeX name parser: fixed parsing of single-word lowercase names and
1915 complex von names, like in “Andrea de Leeuw van Weenen”.
1916 • Fixed broken --label-style and --name-style options.
1918 • Added (autogenerated) manpages.
1920 • Added this changelog.
1922 Version 0.9
1924 (released on August 17, 2009)
1925 • Implemented \citation{*}.
1927 • Implemented crossrefs.
1929 • BibTeX .bib parser now supports newlines inside strings.
1931 • Fixed: .bib filename from .aux file was ignored.
1933 • Fixed incorrect argument passing to codecs.open().
1935 • Fixed incorrect whitespace handling in the name parsing code.
1937 Version 20090402
1939 (released on February 04, 2009)
1940 • Fixed yet more encoding-related bugs.
1942 • Cleaned up some old nasty code, updated the documentation, added more
1944 tests.
1945 Version 20080918
1947 (released on September 18, 2008)
1948 • Added HTML backend. The pythonic bibliography formatter can now pro‐
1950 duce LaTeX, HTML, and plaintext.
1951 • BibTeXML writer now indents the resulting XML.
1953 • Removed the dependency on external elementtree.
1955 • Improved the interface of the pybtex-convert script. It is just con‐
1957 vert foo.bib foo.yaml now.
1958 • Fixed several bugs in the BibTeX interpreter.
1960 • Fixed several encoding-related bugs.
1962 Version 20070513
1964 (released on May 13, 2007)
1965 • Added an interpreter for the BibTeX stack language. Pybtex now sup‐
1967 ports BibTeX style files.
1968 • Added a YAML bibliography format (both input and output).
1970 • Improved processing of names with {braces}.
1972 • Added support for @preamble to both BibTeX parser and writer.
1974 • Introduced an experimental pythonic template language to make bibli‐
1976 ography formatting easier with a more functional-oriented approach.
1977 • Added support for incollection entries to the experimentl pythonic
1979 bibliography style.
1980 • cElementTree is now used for BibTeXML parsing, if present.
1982 • Added some documentation files (finally).
1984 Version 20060416
1986 (released on April 16, 2006)
1987 • Added BibTeX and BibTeXML formatters for bibliography databases.
1989 Added a database conversion tool.
1990 • Improved name splitting in the BibTeX parser.
1992 • Locale encoding is now used by default.
1994 • Added richtext.Check class to simplify formatting of optional bibli‐
1996 ography fields.
1997 • Added support for booklet and inbook entry types to the experimentl
1999 pythonic bibliography style.
2000 Version 20060402
2002 (released on April 2, 2006)
2003 • Added initial Unicode support and input/output encodings.
2005 • Introduced output backends to make bibliography styles markup-inde‐
2007 pendent. Added LaTeX and Plaintext backends.
2008 • Improved BibTeXML parser, add support for pre-parsed names (<bib‐
2010 tex:first>, <bibtex:middle> and so on).
2011 • Added default macros for month names to the BibTeX parser.
2013 • Added an experimental richtext.Phrase (former Pack class (former
2015 Packer class)) class to make creating sentences and delimited lists
2016 easier.
2017 • Added experimental support for pluggable name and label styles to the
2019 pythonic bibliogrphy formatter.
2020 • Made Pybtex work on Windows by renaming aux.py to auxfile.py. Duh.
2022 Version 0.1
2024 (released on March 4, 2006)
2025 Initial release. This version already has a basic BibTeX .bib parser,
2027 BibTeXML parser and a proof-of-concept pythonic bibliography formatter.
2028
2030 Andrey Golovizin
2031
2033 2023, Andrey Golovizin
20340.24.0 Jul 21, 2023 PYBTEX(1)