1PYBTEX(1) Pybtex User’s Guide PYBTEX(1)
2
3
4
6 pybtex - Pybtex Documentation
7
9 • Making bibliographies with pybtex
10
11 • Bibliography formats other then BibTeX
12
13 • Pythonic bibliography styles
14
15 • Converting bibliography databases with bibtex-convert
16
17 • Pretty-printing bibliography databases with bibtex-format
18
19 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
24 For example, to compile the bibliography for a LaTeX file named
25 book.tex, you need to type:
26
27 $ latex book
28 $ pybtex book
29 $ latex book
30 $ latex book # to get cross-references right
31
32 See the BibTeX tutorial by Andrew Roberts for a basic explanation of
33 how to use BibTeX.
34
35 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
40 By default, the BibTeX format is used. If a LaTeX file book.tex con‐
41 tains:
42
43 \bibliography{mybook}
44
45 Then this command:
46
47 $ pybtex book
48
49 will expect to find the bibliography data in a BibTeX-formatted file
50 mybook.bib.
51
52 Pybtex can be instructed to use a different format with the --format
53 option. For example this command:
54
55 $ pybtex --format yaml book
56
57 will tell Pybtex to look for a YAML-formatted file mybook.yaml instead
58 of mybook.bib.
59
60 Support for additional bibliography formats can be added by plugins.
61
62 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
67 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
72 By default, Pybtex uses BibTeX’ .bst styles. You can switch the style
73 language from BibTeX to Python with the --style-language option:
74
75 $ pybtex --style-language python book
76
77 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
82 $ pybtex --style-language python --output-backend html book
83 $ pybtex --style-language python --output-backend plaintext book
84
85 (In this case Pybtex will write the bibliography to book.html or
86 book.txt instead of book.bbl.)
87
88 Support for other markup formats can be added by plugins.
89
90 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
96 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
100 $ pybtex-convert book.bib book.yaml
101
102 Be aware that the conversion is not always lossless. For example:
103
104 • BibTeX’ string macros are substituted by their values during conver‐
105 sion.
106
107 • BibTeXML does not support LaTeX preambles.
108
109 • 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
113 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
118 $ pybtex-format book.bib book.txt
119 $ pybtex-format book.bib book.html
120
121 By default, the unsrt style is used for formatting. This can be
122 changed with the --style option:
123
124 $ pybtex-format --style alpha book.bib book.txt
125
127 • Bibliography formats
128
129 • BibTeX
130
131 • BibTeXML
132
133 • YAML
134
135 • Bibliography style formats
136
137 • Output formats
138
139 Bibliography formats
140 BibTeX
141 BibTeX is the default bibliography format used by Pybtex:
142
143 @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
151 Some links:
152
153 • A basic description of the BibTeX format.
154
155 • An in-depth description of the quirky BibTeX syntax.
156
157 BibTeXML
158 BibTeXML is an attempt to translate the BibTeX format into XML. The
159 above BibTeX snippet translates into this XML:
160
161 <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
182 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
186 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
200 Bibliography style formats
201 Pybtex currently supports bibliography styles in two formats:
202
203 • BibTeX’ .bst files
204
205 • Pybtex’ Pythonic styles
206
207 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
212 • LaTeX
213
214 • Markdown
215
216 • HTML
217
218 • plain text
219
220 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
228 • Writing bibliography data
229
230 • Bibliography data classes
231
232 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
237 pybtex.database.parse_string(value, bib_format, **kwargs)
238 Parse a Unicode string containing bibliography data and return a
239 BibliographyData object.
240
241 Parameters
242
243 • value – Unicode string.
244
245 • bib_format – Data format (“bibtex”, “yaml”, etc.).
246
247 New in version 0.19.
248
249
250 pybtex.database.parse_bytes(value, bib_format, **kwargs)
251 Parse a byte string containing bibliography data and return a
252 BibliographyData object.
253
254 Parameters
255
256 • value – Byte string.
257
258 • bib_format – Data format (for example, “bibtexml”).
259
260 New in version 0.19.
261
262
263 pybtex.database.parse_file(file, bib_format=None, **kwargs)
264 Read bibliography data from file and return a BibliographyData
265 object.
266
267 Parameters
268
269 • file – A file name or a file-like object.
270
271 • bib_format – Data format (“bibtex”, “yaml”, etc.). If
272 not specified, Pybtex will try to guess by the file
273 name.
274
275 New in version 0.19.
276
277
278 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
282 Here is a quick example:
283
284 >>> 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
293 Writing bibliography data
294 The BibliographyData class has several methods that are symmetrical to
295 the functions described above:
296
297 • BibliographyData.to_string() formats the bibliograhy data into a
298 string,
299
300 • BibliographyData.to_bytes() formats the bibliograhy data into a byte
301 string,
302
303 • BibliographyData.to_file() writes the bibliograhy data to a file.
304
305 >>> 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
322
323 Bibliography data classes
324 Pybtex uses several classes to represent bibligraphy databases:
325
326 • BibliographyData is a collection of individual bibliography entries
327 and some additional metadata.
328
329 • Entry is a single bibliography entry (a book, an article, etc.).
330
331 An entry has a key (like "knuth74"), a type ("book", "article",
332 etc.), and a number of key-value fields ("author", "title", etc.).
333
334 • Person is a person related to a bibliography entry (usually as an au‐
335 thor or an editor).
336
337 class pybtex.database.BibliographyData(entries=None, preamble=None,
338 wanted_entries=None, min_crossrefs=2)
339
340 entries
341 A dictionary of bibliography entries referenced by their
342 keys.
343
344 The dictionary is case insensitive:
345
346 >>> 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
355 property preamble
356 LaTeX preamble.
357
358 >>> bib_data = parse_string(r"""
359 ... @PREAMBLE{"\newcommand{\noopsort}[1]{}"}
360 ... """, 'bibtex')
361 >>> print(bib_data.preamble)
362 \newcommand{\noopsort}[1]{}
363
364 New in version 0.19: Earlier versions used
365 get_preamble(), which is now deprecated.
366
367
368 get_preamble()
369 Deprecated since version 0.19: Use preamble instead.
370
371
372 to_string(bib_format, **kwargs)
373 Return the data as a unicode string in the given format.
374
375 Parameters
376 bib_format – Data format (“bibtex”, “yaml”, etc.).
377
378 New in version 0.19.
379
380
381 classmethod from_string(value, bib_format, **kwargs)
382 Return the data from a unicode string in the given for‐
383 mat.
384
385 Parameters
386 bib_format – Data format (“bibtex”, “yaml”, etc.).
387
388 New in version 0.22.2.
389
390
391 to_bytes(bib_format, **kwargs)
392 Return the data as a byte string in the given format.
393
394 Parameters
395 bib_format – Data format (“bibtex”, “yaml”, etc.).
396
397 New in version 0.19.
398
399
400 to_file(file, bib_format=None, **kwargs)
401 Save the data to a file.
402
403 Parameters
404
405 • file – A file name or a file-like object.
406
407 • bib_format – Data format (“bibtex”, “yaml”,
408 etc.). If not specified, Pybtex will try to
409 guess by the file name.
410
411 New in version 0.19.
412
413
414 lower()
415 Return another BibliographyData with all identifiers con‐
416 verted to lowercase.
417
418 >>> 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
442 class pybtex.database.Entry(type_, fields=None, persons=None)
443 A bibliography entry.
444
445 key = None
446 Entry key (for example, 'fukushima1980neocognitron').
447
448 type = None
449 Entry type ('book', 'article', etc.).
450
451 fields = None
452 A dictionary of entry fields. The dictionary is ordered
453 and case-insensitive.
454
455 persons = None
456 A dictionary of entry persons, by their roles.
457
458 The most often used roles are 'author' and 'editor'.
459
460 to_string(bib_format, **kwargs)
461 Return the data as a unicode string in the given format.
462
463 Parameters
464 bib_format – Data format (“bibtex”, “yaml”, etc.).
465
466 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
471 Parameters
472
473 • bib_format – Data format (“bibtex”, “yaml”,
474 etc.).
475
476 • entry_number – entry number if the string has
477 more than one.
478
479 New in version 0.22.2.
480
481
482 class pybtex.database.Person(string='', first='', middle='',
483 prelast='', last='', lineage='')
484 A person or some other person-like entity.
485
486 >>> knuth = Person('Donald E. Knuth')
487 >>> knuth.first_names
488 ['Donald']
489 >>> knuth.middle_names
490 ['E.']
491 >>> knuth.last_names
492 ['Knuth']
493
494 first_names = None
495 A list of first names.
496
497 New in version 0.19: Earlier versions used first(), which
498 is now deprecated.
499
500
501 middle_names = None
502 A list of middle names.
503
504 New in version 0.19: Earlier versions used middle(),
505 which is now deprecated.
506
507
508 prelast_names = None
509 A list of pre-last (aka von) name parts.
510
511 New in version 0.19: Earlier versions used middle(),
512 which is now deprecated.
513
514
515 last_names = None
516 A list of last names.
517
518 New in version 0.19: Earlier versions used last(), which
519 is now deprecated.
520
521
522 lineage_names = None
523 A list of linage (aka Jr) name parts.
524
525 New in version 0.19: Earlier versions used lineage(),
526 which is now deprecated.
527
528
529 property bibtex_first_names
530 A list of first and middle names together. (BibTeX
531 treats all middle names as first.)
532
533 New in version 0.19: Earlier versions used
534 Person.bibtex_first(), which is now deprecated.
535
536
537 >>> knuth = Person('Donald E. Knuth')
538 >>> knuth.bibtex_first_names
539 ['Donald', 'E.']
540
541 get_part(type, abbr=False)
542 Get a list of name parts by type.
543
544 >>> knuth = Person('Donald E. Knuth')
545 >>> knuth.get_part('first')
546 ['Donald']
547 >>> knuth.get_part('last')
548 ['Knuth']
549
550 property rich_first_names
551 A list of first names converted to rich text.
552
553 New in version 0.20.
554
555
556 property rich_middle_names
557 A list of middle names converted to rich text.
558
559 New in version 0.20.
560
561
562 property rich_prelast_names
563 A list of pre-last (aka von) name parts converted to rich
564 text.
565
566 New in version 0.20.
567
568
569 property rich_last_names
570 A list of last names converted to rich text.
571
572 New in version 0.20.
573
574
575 property rich_lineage_names
576 A list of lineage (aka Jr) name parts converted to rich
577 text.
578
579 New in version 0.20.
580
581
582 first(abbr=False)
583 Deprecated since version 0.19: Use first_names instead.
584
585
586 middle(abbr=False)
587 Deprecated since version 0.19: Use middle_names instead.
588
589
590 prelast(abbr=False)
591 Deprecated since version 0.19: Use prelast_names instead.
592
593
594 last(abbr=False)
595 Deprecated since version 0.19: Use last_names instead.
596
597
598 lineage(abbr=False)
599 Deprecated since version 0.19: Use lineage_names instead.
600
601
602 bibtex_first()
603 Deprecated since version 0.19: Use bibtex_first_names in‐
604 stead.
605
606
607 Formatting bibliographies
608 • BibTeX engine
609
610 • How it works
611
612 • Python engine
613
614 • Differences from the BibTeX engine
615
616 • How it works
617
618 • Python API
619
620 • The base interface
621
622 • The BibTeXEngine class
623
624 • The PybtexEngine class
625
626 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
630 @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
637 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
641 Pybtex contains two different formatting engines:
642
643 • The BibTeX engine uses BibTeX .bst styles.
644
645 • The Python engine uses styles written in Python.
646
647 BibTeX engine
648 The BibTeX engine is fully compatible with BibTeX style files and is
649 used by default.
650
651 How it works
652 When you type pybtex mydocument, the following things happen:
653
654 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
658 Pybtex is interested in these three pieces of information:
659
660 Bibliography style:
661 First, Pybtex searches the .aux file for a \bibstyle command
662 that specifies which formatting style will be used.
663
664 For example, \bibstyle{unsrt} instructs Pybtex to use format‐
665 ting style defined in the file unsrt.bst.
666
667 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
672 For example, \bibdata{mydocument} means “use the bibliography
673 data from mydocument.bib”.
674
675 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
680 For example, \citation{graham1989concrete} means “include the
681 entry with the key graham1989concrete into the resulting bib‐
682 liograhy”.
683
684 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
688 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
692 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
695 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
708 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
719 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
723 Python engine
724 The Python engine is enabled by running pybtex with the -l python op‐
725 tion.
726
727 Differences from the BibTeX engine
728 • Formatting styles are written in Python instead of the .bst language.
729
730 • Formatting styles are not tied to LaTeX and do not use hardcoded La‐
731 TeX markup. Instead of that they produce format-agnostic pybtex.rich‐
732 text.Text objects that can be converted to any markup format (LaTeX,
733 Markdown, HTML, etc.).
734
735 • Name formatting, label formatting, and sorting styles are defined
736 separately from the main style.
737
738 How it works
739 When you type pybtex -l python mydocument, this things happen:
740
741 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
746 2. Pybtex reads the biliography data from all data files specified in
747 the .aux file into a single BibliographyData object.
748
749 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
754 4. The formatting style formats each of the requested bibliography en‐
755 tries in a style-specific way.
756
757 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
765 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
774 Formatted entries are put into a FormattedBibliography object—it
775 simply contains a list of FormattedEntry objects and some additional
776 metadata.
777
778 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
784 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
789 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
793 class pybtex.Engine
794
795 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
800 Parameters
801 style – If not None, use this style instead of
802 specified in the .aux file.
803
804 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
809 This is a convenience method that calls
810 format_from_strings() with a single string.
811
812 format_from_strings(bib_strings, *args, **kwargs)
813 Parse the bigliography data from the given strings and
814 produce a formated bibliography.
815
816 This is a convenience method that wraps each string into
817 a StringIO, then calls format_from_files().
818
819 format_from_file(filename, *args, **kwargs)
820 Read the bigliography data from the given file and pro‐
821 duce a formated bibliography.
822
823 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
827 format_from_files(**kwargs)
828 Read the bigliography data from the given files and pro‐
829 duce a formated bibliography.
830
831 This is an abstract method overridden by both
832 pybtex.PybtexEngine and pybtex.bibtex.BibTeXEngine.
833
834 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
839 class pybtex.bibtex.BibTeXEngine
840 The Python fomatting engine.
841
842 See pybtex.Engine for inherited methods.
843
844 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
851 Parameters
852
853 • bib_files_or_filenames – A list of file names or
854 file objects.
855
856 • style – The name of the formatting style.
857
858 • citations – A list of citation keys.
859
860 • bib_format – The name of the bibliography for‐
861 mat. The default format is bibtex.
862
863 • bib_encoding – Encoding of bibliography files.
864
865 • output_encoding – Encoding that will be used by
866 the output backend.
867
868 • bst_encoding – Encoding of the .bst file.
869
870 • min_crossrefs – Include cross-referenced entries
871 after this many crossrefs. See BibTeX manual for
872 details.
873
874 • 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
878 • add_output_suffix – Append a .bbl suffix to the
879 output file name.
880
881 pybtex.bibtex.make_bibliography(*args, **kwargs)
882 A convenience function that calls BibTeXEngine.make_bibliogra‐
883 phy().
884
885 pybtex.bibtex.format_from_string(*args, **kwargs)
886 A convenience function that calls BibTeXEngine.for‐
887 mat_from_string().
888
889 pybtex.bibtex.format_from_strings(*args, **kwargs)
890 A convenience function that calls BibTeXEngine.for‐
891 mat_from_strings().
892
893 pybtex.bibtex.format_from_file(*args, **kwargs)
894 A convenience function that calls BibTeXEngine.for‐
895 mat_from_file().
896
897 pybtex.bibtex.format_from_files(*args, **kwargs)
898 A convenience function that calls
899 BibTeXEngine.format_from_files().
900
901 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
906 class pybtex.PybtexEngine
907 The Python fomatting engine.
908
909 See pybtex.Engine for inherited methods.
910
911 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
918 Parameters
919
920 • bib_files_or_filenames – A list of file names or
921 file objects.
922
923 • style – The name of the formatting style.
924
925 • citations – A list of citation keys.
926
927 • bib_format – The name of the bibliography for‐
928 mat. The default format is bibtex.
929
930 • bib_encoding – Encoding of bibliography files.
931
932 • output_backend – Which output backend to use.
933 The default is latex.
934
935 • output_encoding – Encoding that will be used by
936 the output backend.
937
938 • bst_encoding – Encoding of the .bst file.
939
940 • min_crossrefs – Include cross-referenced entries
941 after this many crossrefs. See BibTeX manual for
942 details.
943
944 • 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
948 • add_output_suffix – Append default suffix to the
949 output file name (.bbl for LaTeX, .html for
950 HTML, etc.).
951
952 pybtex.make_bibliography(*args, **kwargs)
953 A convenience function that calls PybtexEngine.make_bibliogra‐
954 phy().
955
956 pybtex.format_from_string(*args, **kwargs)
957 A convenience function that calls PybtexEngine.for‐
958 mat_from_string().
959
960 pybtex.format_from_strings(*args, **kwargs)
961 A convenience function that calls PybtexEngine.for‐
962 mat_from_strings().
963
964 pybtex.format_from_file(*args, **kwargs)
965 A convenience function that calls PybtexEngine.for‐
966 mat_from_file().
967
968 pybtex.format_from_files(*args, **kwargs)
969 A convenience function that calls
970 PybtexEngine.format_from_files().
971
972 Designing styles
973 • Rich text
974
975 • Rich text classes
976
977 • Style API
978
979 • Template language
980
981 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
987 • plain text parts, represented by String objects,
988
989 • formatted parts, represented by Tag and HRef objects.
990
991 The basic workflow is:
992
993 1. Construct a Text object.
994
995 2. Render it as LaTeX, HTML or other markup.
996
997 >>> 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
1004 Rich text classes
1005 There are several rich text classes in Pybtex:
1006
1007 • Text
1008
1009 • String
1010
1011 • Tag
1012
1013 • HRef
1014
1015 • Protected
1016
1017 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
1021 String is just a wrapper for a single Python string.
1022
1023 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
1028 is represented by this object tree:
1029
1030 >>> 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
1039 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
1044 All rich text classes share the same API which is more or less similar
1045 to plain Python strings.
1046
1047 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
1053 Here we document the methods of the Text class. The other classes have
1054 the same methods.
1055
1056 class pybtex.richtext.Text(*parts)
1057 The Text class is the top level container that may contain
1058 String, Tag or HRef objects.
1059
1060 __init__(*parts)
1061 Create a text object consisting of one or more parts.
1062
1063 Empty parts are ignored:
1064
1065 >>> Text() == Text('') == Text('', '', '')
1066 True
1067 >>> Text('Word', '') == Text('Word')
1068 True
1069
1070 Text() objects are unpacked and their children are in‐
1071 cluded directly:
1072
1073 >>> 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
1078 Similar objects are merged together:
1079
1080 >>> 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
1085 __eq__(other)
1086 Rich text objects support equality comparison:
1087
1088 >>> Text('Cat') == Text('cat')
1089 False
1090 >>> Text('Cat') == Text('Cat')
1091 True
1092
1093 __len__()
1094 len(text) returns the number of characters in the text,
1095 ignoring the markup:
1096
1097 >>> 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
1104 __contains__(item)
1105 value in text returns True if any part of the text con‐
1106 tains the substring value:
1107
1108 >>> 'Long cat' in Text('Long cat!')
1109 True
1110
1111 Substrings splitted across multiple text parts are not
1112 matched:
1113
1114 >>> 'Long cat' in Text(Tag('em', 'Long'), 'cat!')
1115 False
1116
1117 __getitem__(key)
1118 Slicing and extracting characters works like with regular
1119 strings, formatting is preserved.
1120
1121 >>> 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
1126 __add__(other)
1127 Concatenate this Text with another Text or string.
1128
1129 >>> Text('Longcat is ') + Tag('em', 'long')
1130 Text('Longcat is ', Tag('em', 'long'))
1131
1132 add_period(period='.')
1133 Add a period to the end of text, if the last character is
1134 not “.”, “!” or “?”.
1135
1136 >>> text = Text("That's all, folks")
1137 >>> print(six.text_type(text.add_period()))
1138 That's all, folks.
1139
1140 >>> text = Text("That's all, folks!")
1141 >>> print(six.text_type(text.add_period()))
1142 That's all, folks!
1143
1144 append(text)
1145 Append text to the end of this text.
1146
1147 For Tags, HRefs, etc. the appended text is placed inside
1148 the tag.
1149
1150 >>> 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
1156 capfirst()
1157 Capitalize the first letter of the text.
1158
1159 >>> Text(Tag('em', 'long Cat')).capfirst()
1160 Text(Tag('em', 'Long Cat'))
1161
1162 capitalize()
1163 Capitalize the first letter of the text and lowercase the
1164 rest.
1165
1166 >>> Text(Tag('em', 'LONG CAT')).capitalize()
1167 Text(Tag('em', 'Long cat'))
1168
1169 endswith(suffix)
1170 Return True if the text ends with the given suffix.
1171
1172 >>> Text('Longcat!').endswith('cat!')
1173 True
1174
1175 Suffixes split across multiple parts are not matched:
1176
1177 >>> Text('Long', Tag('em', 'cat'), '!').endswith('cat!')
1178 False
1179
1180 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
1185 join(parts)
1186 Join a list using this text (like string.join)
1187
1188 >>> 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
1194 lower()
1195 Convert rich text to lowercase.
1196
1197 >>> Text(Tag('em', 'Long cat')).lower()
1198 Text(Tag('em', 'long cat'))
1199
1200 render(backend)
1201 Render this Text into markup.
1202
1203 Parameters
1204 backend – The formatting backend (an instance of
1205 pybtex.backends.BaseBackend).
1206
1207 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
1212 >>> 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
1220 Parameters
1221 backend_name – The name of the output backend
1222 (like "latex" or "html").
1223
1224 split(sep=None, keep_empty_parts=None)
1225
1226 >>> Text('a + b').split()
1227 [Text('a'), Text('+'), Text('b')]
1228
1229 >>> Text('a, b').split(', ')
1230 [Text('a'), Text('b')]
1231
1232 startswith(prefix)
1233 Return True if the text starts with the given prefix.
1234
1235 >>> Text('Longcat!').startswith('Longcat')
1236 True
1237
1238 Prefixes split across multiple parts are not matched:
1239
1240 >>> Text(Tag('em', 'Long'), 'cat!').startswith('Longcat')
1241 False
1242
1243 upper()
1244 Convert rich text to uppsercase.
1245
1246 >>> Text(Tag('em', 'Long cat')).upper()
1247 Text(Tag('em', 'LONG CAT'))
1248
1249 class pybtex.richtext.String(*parts)
1250 A String is a wrapper for a plain Python string.
1251
1252 >>> 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
1258 String supports the same methods as Text.
1259
1260 class pybtex.richtext.Tag(name, *args)
1261 A Tag represents something like an HTML tag or a LaTeX format‐
1262 ting command:
1263
1264 >>> 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
1271 Tag supports the same methods as Text.
1272
1273 class pybtex.richtext.HRef(url, *args)
1274 A HRef represends a hyperlink:
1275
1276 >>> 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
1283 >>> href = HRef(String('http://ctan.org/'), String('http://ctan.org/'))
1284 >>> print(href.render_as('latex'))
1285 \url{http://ctan.org/}
1286
1287 HRef supports the same methods as Text.
1288
1289 class pybtex.richtext.Protected(*args)
1290 A Protected represents a “protected” piece of text.
1291
1292 • Protected.lower(), Protected.upper(), Protected.capitalize(),
1293 and Protected.capitalize() are no-ops and just return the
1294 Protected object itself.
1295
1296 • Protected.split() never splits the text. It always returns a
1297 one-element list containing the Protected object itself.
1298
1299 • In LaTeX output, Protected is {surrounded by braces}. HTML
1300 and plain text backends just output the text as-is.
1301
1302 >>> 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
1313 New in version 0.20.
1314
1315
1316 class pybtex.richtext.Symbol(name)
1317 A special symbol. This class is rarely used and may be removed
1318 in future versions.
1319
1320 Examples of special symbols are non-breaking spaces and dashes.
1321
1322 Symbol supports the same methods as Text.
1323
1324 Style API
1325 A formatting style in Pybtex is a class inherited from
1326 pybtex.style.formatting.BaseStyle.
1327
1328 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
1333 format_bibliography(bib_data, citations=None)
1334 Format bibliography entries with the given keys and re‐
1335 turn a FormattedBibliography object.
1336
1337 Parameters
1338
1339 • bib_data – A pybtex.database.BibliographyData
1340 object.
1341
1342 • citations – A list of citation keys.
1343
1344 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
1355 An example minimalistic style:
1356
1357 from pybtex.style.formatting import BaseStyle
1358 from pybtex.richtext import Text, Tag
1359
1360 class MyStyle(BaseStyle):
1361 def format_article(self, entry):
1362 return Text('Article ', Tag('em', entry.fields['title']))
1363
1364 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
1369 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
1373 An example formatting style using template language:
1374
1375 from pybtex.style.formatting import BaseStyle, toplevel
1376 from pybtex.style.template import field, join, optional
1377
1378 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
1392 Extending Pybtex with plugins
1393 • Entry points
1394
1395 • pybtex.database.input
1396
1397 • pybtex.database.output
1398
1399 • pybtex.backends
1400
1401 • pybtex.style.formatting
1402
1403 • pybtex.style.labels
1404
1405 • pybtex.style.names
1406
1407 • pybtex.style.sorting
1408
1409 • Registering plugins
1410
1411 • Example plugins
1412
1413 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
1417 The plugins are based on Setuptools’ entry points.
1418
1419 Entry points
1420 Here is the list of entry points supported by Pybtex.
1421
1422 pybtex.database.input
1423 This entry point is used for bibliography parsers. Must point to a
1424 subclass of pybtex.database.input.BaseParser.
1425
1426 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
1430 For example, a JSON input plugin could use these entry points:
1431
1432 [pybtex.database.input]
1433 json = pybtexjson:JSONParser
1434
1435 [pybtex.database.input.suffixes]
1436 .json = pybtexjson:JSONParser
1437
1438 pybtex.database.output
1439 This entry poing is used for bibliography writers. Must point to a
1440 subclass of pybtex.database.output.BaseWriter.
1441
1442 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
1447 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
1452 pybtex.style.formatting
1453 This is the entry point for Pythonic bibliography styles. Must point to
1454 a pybtex.style.formatting.BaseStyle subclass.
1455
1456 pybtex.style.labels
1457 Label styles for Pythonic bibliography styles.
1458
1459 pybtex.style.names
1460 Name styles for Pythonic bibliography styles.
1461
1462 pybtex.style.sorting
1463 Sorting styles for Pythonic bibliography styles.
1464
1465 Registering plugins
1466 See Setuptools’ documentation.
1467
1468 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
1476 This is the last version that supports Python 2. The next version will
1477 require Python 3.6 or above.
1478
1479 • Added support for sup and sub tags to LaTeX and Markdown backends.
1480
1481 • Added support for @online entries and the urldate field.
1482
1483 • Restored compatibility with Python 2.
1484
1485 • Fixed tests on Windows.
1486
1487 • Fixed bugs in the example plugin.
1488
1489 • Fixed bad get_default_encoding() call.
1490
1491 Thanks to Matthias Troffaes for his contributions!
1492
1493 Version 0.23.0
1494 (released on October 12, 2020)
1495
1496 • Reimplemented OrderedCaseInsensitiveDict using python:collections.Or‐
1497 deredDict (so it has a __delitem__).
1498
1499 • unsrt.py now supports type when formatting phdthesis.
1500
1501 • Added from_string() to pybtex.database.BibliographyData.
1502
1503 • Added from_string() and to_string() to pybtex.database.Entry.
1504
1505 • Added indentation to __repr__ in pybtex.database.BibliographyData and
1506 pybtex.database.Entry.
1507
1508 • Preserve order in pybtex.utils.OrderedCaseInsensitiveDict.__repr__().
1509
1510 • Fixed entries with duplicate keys being removed during sorting.
1511
1512 • Fixed handling of duplicate person fields
1513
1514 • Use ElementTree instead of the deprecated cElementTree.
1515
1516 • Import base classes from python:collections.abc instead of
1517 python:collections.
1518
1519 • Use __iter__ instead of deprecated Element.getchildren().
1520
1521 Thanks to David Chiang, Jerry James, Jannik Schürg, Nathaniel Starkman,
1522 and Matthias Troffaes for their fixes and improvements!
1523
1524 Version 0.22.2
1525 (released on January 17, 2019)
1526
1527 • Fixed compatibility with Python 2 and older versions of Python 3.
1528
1529 Version 0.22.1
1530 (released on January 16, 2019)
1531
1532 • Fixed non-working --backend option with pybtex -l python.
1533
1534 Version 0.22.0
1535 (released on November 18, 2018)
1536
1537 • Fixed handling of duplicate fields in .bib biles. Thanks, Jannik
1538 Schürg!
1539
1540 • BibTeX parser is now up to 10% faster on some files. Thanks, Fabrice
1541 Benhamouda!
1542
1543 • Fixed parsing of names with \~ characters.
1544
1545 • Fixed formatting proceedings without an editor field in unsrt.py.
1546
1547 • In case of too many braces in a BibTeX string, PybtexSyntaxError is
1548 now raised instead of RecursionError.
1549
1550 • Dropped 2to3, made the code compatible with both Python 2 and 3 with
1551 Six.
1552
1553 • Moved tests outside of the pybtex package.
1554
1555 • Fixed searching in docs with recent versions of Sphinx.
1556
1557 • API: renamed bibtex.BibTeXEntryIterator to bibtex.LowLevelParser for
1558 clarity.
1559
1560 • API: removed confusing usage of Person.text in tempate.names.
1561
1562 • API: Entry.fields does not automagically look for cross-referenced
1563 entries anymore.
1564
1565 Version 0.21
1566 (released on January 20, 2017)
1567
1568 • BibTeX writer now uses latexcodec to encode characters that are not
1569 directly supported by the output encoding. Thanks, Hong Xu!
1570
1571 • HTML backend: {braced stings} are now wrapped with <span class="bib‐
1572 tex-protected"> to enable custom CSS styling.
1573
1574 • unsrt.py: DOI, PubMed and Arxiv links now use HTTPS instead of HTTP.
1575
1576 • unsrt.py: URLs with percent characters are now formatted correctly.
1577
1578 • unsrt.py: short page / volume / chapter numbers are now joined with a
1579 non-breaking space, like in BibTeX.
1580
1581 • unsrt.py: inbook now uses the editor field if the author field is
1582 missing, like in BibTeX.
1583
1584 • unsrt.py: the words “volume” and “pages” in the beginning of the sen‐
1585 tence are now capitalized, like in BibTeX.
1586
1587 • unsrt.py: removed unnecessary period between the book title and the
1588 comma in inbook.
1589
1590 Version 0.20.1
1591 (released on March 17, 2016)
1592
1593 • LaTeX backend: fix encoding tilde ("~") characters with newer ver‐
1594 sions of latexcodec.
1595
1596 • Fix splitting names with escaped space ("\ ") characters.
1597
1598 Version 0.20
1599 (released on March 10, 2016)
1600
1601 • YAML reader and writer now preserve the order of bibliography en‐
1602 tries.
1603
1604 • Improved URL formatting in pythonic styles.
1605
1606 • Built-in pythonic styles now support the ISBN field.
1607
1608 • Pythonic styles now treat LaTeX braces correctly:
1609
1610 • case conversion does not affect {braced substrings},
1611
1612 • braces are stripped from non-LaTeX output: "{P}ython" becomes
1613 "Python".
1614
1615 • Pythonic styles now use latexcodec to decode LaTeX markup. For exam‐
1616 ple, "Schr\"odinger" is now correctly rendered as "Schrödinger" in
1617 HTML or plain text.
1618
1619 Thanks to Hong Xu for his contributions!
1620
1621 Version 0.19
1622 (released on October 26, 2015)
1623
1624 • Added Markdown output format (contributed by Jorrit Wronski).
1625
1626 • Incorrectly formatted author and editor names now result in warnings
1627 instead of errors, unless --strict mode is enabled.
1628
1629 • Fixed HTML escaping.
1630
1631 • Fixed parsing nested .aux files.
1632
1633 • Fixed splitting names separated by non-lowercase " and ".
1634
1635 • Fixed line numbers in error messages when parsing strings with
1636 DOS/Windows line breaks.
1637
1638 • Fixed compatibility with BibTeX when parsing certain weird “von”
1639 names.
1640
1641 • Removed excessive trailing newline from .bib output.
1642
1643 • Text wrapping now works exactly as in BibTeX.
1644
1645 • Added new API for reading and writing bibliography data.
1646
1647 • Pythonic styles: reworked and extended the rich text API.
1648
1649 • Pythonic styles: added strong, i, b, tt tags, renamed the old emph
1650 tag to em.
1651
1652 • Pythonic styles: the author_year_title style now returns "" instead
1653 of None (fixes unorderable types error in Python 3).
1654
1655 • Ported the documentation to Sphinx.
1656
1657 Thanks to Jorrit Wronski and Matthias Troffaes for their fixes and im‐
1658 provements!
1659
1660 Version 0.18
1661 (released on July 6, 2014)
1662
1663 • Pybtex is now fully case-insensitive (like BibTeX). As a consequence,
1664 IEEEtran styles now work correctly.
1665
1666 • Added --preserve-case option to pybtex-convert (default behavior is
1667 to converted all identifiers to lower case).
1668
1669 • An error is reported if two citations have the same key but different
1670 case, like in BibTeX. (Example: ddt1999 and DDT1999).
1671
1672 • Fixed parsing unused bibliography entries with strings containing @
1673 characters.
1674
1675 • entry.max$ constant is now set to 250, global.max$ is set to 20000,
1676 like in BibTeX.
1677
1678 • Added --strict option to pybtex-convert and pybtex-format (turns
1679 warning into errors).
1680
1681 • Strict mode is now enabled by default when using pybtex as a library
1682 (exceptions are raised on all errors instead of just printing warn‐
1683 ings to stderr).
1684
1685 Non-strict error handling is still enabled when using pybtex from the
1686 command line, for compatibility with BibTeX. Use --strict option if
1687 you don’t like this.
1688
1689 • Added missing pybtex-format manpage.
1690
1691 Version 0.17
1692 (released on March 10, 2014)
1693
1694 • Added pybtex-format utility for formatting bibliography files as
1695 HTML, LaTeX, and other supported human-readable formats.
1696
1697 • Added --strict command line option to pybtex (all warnings become er‐
1698 rors).
1699
1700 • Added alpha label style, and alpha and unsrtalpha formatting styles.
1701
1702 • Added support for url, eprint, doi, and pubmed fields in unsrt style.
1703
1704 • Names with hyphens are now abbreviated correctly (“Jean-Baptiste” be‐
1705 comes “J.-B.”).
1706
1707 • width$ now uses cmr10 font metrics, like in BibTeX. Non-latin charac‐
1708 ters are also supported.
1709
1710 • Pythonic style engine now supports @preamble commands.
1711
1712 • Warning on missing fields are now more human-readable.
1713
1714 • When writing BibTeX files, put entry key on the same line with entry
1715 type. Fixes warnings in Jabref.
1716
1717 • When using multiple .bib files, macros defined in earlier files are
1718 available in subsequent ones (like in BibTeX).
1719
1720 • Fixed parsing .bst files with lines consisting of a single % charac‐
1721 ter.
1722
1723 • Fixed sorting entries without author in author_year_title sorting
1724 style.
1725
1726 • Fixed broken CaseInsensitiveDict.get().
1727
1728 • CaseInsensitiveDict is now pickleable.
1729
1730 • Added support for registering plugins at runtime with pyb‐
1731 tex.plugin.register_plugin() - useful for using pybtex as a library.
1732
1733 Many thanks to Matthias C. M. Troffaes for his numerous fixes and im‐
1734 provements!
1735
1736 Version 0.16
1737 (released on March 17, 2012)
1738
1739 • BibTeX .bib and .bst parsers were completely rewritten. They are now
1740 much faster and more BibTeX-compatible.
1741
1742 • Syntax errors and undefined strings in .bib files now result in warn‐
1743 ings instead of errors, like in BibTeX.
1744
1745 • Unused entries in .bib files are now skipped, like in BibTeX.
1746
1747 • The case of entry keys is now preserved (in previous versions they
1748 were converted to lowercase).
1749
1750 • Pythonic style engine now supports sorting.
1751
1752 • Pythonic style engine: fixed nested optional() blocks.
1753
1754 • Fixed parsing of some names with a Last part but no von part.
1755
1756 • Fixed processing of brace-level-one “special characters” in purify$
1757 BibTeX built-in function.
1758
1759 • Added proper error messages on encoding errors in .bib files.
1760
1761 • The default encoding is now UTF-8 on all platforms.
1762
1763 • pybtex-convert now preserves the order of entries in BibTeX and Bib‐
1764 TeXML files.
1765
1766 The following changes were contributed by Matthias C. M. Troffaes:
1767
1768 • Fixed first_of behavior when non-empty child is followed by a child
1769 that has a missing field.
1770
1771 • Fixed crossref lookups when key is not lower case.
1772
1773 • Completed unsrt and plain python styles: they now contain all entry
1774 types.
1775
1776 • Added doctree backend for rendering into a tree of docutils nodes.
1777
1778 • Added support for non-string backends.
1779
1780 Version 0.15
1781 (released on February 1, 2011)
1782
1783 • Changed license from GPL-3 to MIT.
1784
1785 • Added support for setuptools plugins.
1786
1787 • BibTeX parser: fixed whitespace normalization in concatenated
1788 strings.
1789
1790 • BibTeX parser: when parsing multiple BibTeX files, macros defined in
1791 earlier files are now available to all subsequent files, like in Bib‐
1792 TeX.
1793
1794 • BibTeX .bst interpreter now prints warnings on missing entries, like
1795 BibTeX, instead of raising a KeyError.
1796
1797 • call.type$ BibTeX built-in function now uses default.entry for un‐
1798 known entry types, like in BibTeX.
1799
1800 • substring$ now accepts start=0 and returns an empty string.
1801
1802 • change.case$: fixed incorrect formatting of strings starting with
1803 special characters with "t" format.
1804
1805 • Fixed abbreviation of names starting with special characters or
1806 non-alphabetic characters.
1807
1808 • Fixed incorrect entry order and duplicated entries with \nocite{*}.
1809
1810 • Added more detailed error messages for already defined variables in
1811 .bst files.
1812
1813 Version 0.14.1
1814 (released on September 30, 2010)
1815
1816 • Added missing custom_fixers directory to the tarball — needed only
1817 for converting the sources to Python 3.
1818
1819 Version 0.14
1820 (released on September 20, 2010)
1821
1822 • BibTeX writer: fixed quoting " (double quote) characters.
1823
1824 • BibTeX parser now produces human-readable error messages on unread
1825 macros.
1826
1827 • Added error messages on missing data in .aux files.
1828
1829 • Improved performance on very long name lists.
1830
1831 • Added support for Python 3.
1832
1833 Version 0.13.2
1834 (released on February 26, 2010)
1835
1836 • BibTeX parser: fixed a bug with parsing strings containing braces,
1837 like "Error in {DNA}".
1838
1839 Version 0.13.1
1840 (released on February 18, 2010)
1841
1842 • Fixed ImportError: No module named kpathsea errors. One of the source
1843 files was missing from pybtex-0.13.tar.bz2 for some strange reason.
1844 Sorry about that. ;)
1845
1846 Version 0.13
1847 (released on February 14, 2010)
1848
1849 • Implemented --min-crossrefs option.
1850
1851 • All command line options of the original BibTeX are not supported.
1852
1853 • Pybtex now respects BSTINPUTS, BIBINPUTS and TEXMFOUTPUT environment
1854 variables.
1855
1856 • BibTeX bibliography parser now strips excessive whitespace from
1857 fields, like BibTeX does.
1858
1859 Version 0.12
1860 (released on November 21, 2009)
1861
1862 • Pybtex now works correctly with \input{filename} in LaTeX files.
1863
1864 • Added a proper change.case$ BibTeX function instead of a stub.
1865
1866 • Added -e/--encoding command line option.
1867
1868 • Fixed non-working --bibtex-encoding option.
1869
1870 • Added proper error messages on missing plugins, file IO errors, some
1871 BibTeX interpreter errors, etc.
1872
1873 • Fallback to backslash-encoding when printing messages to the console
1874 - to make them printable regardless of the locale.
1875
1876 Version 0.11
1877 (released on September 7, 2009)
1878
1879 • Made text.lentgh$ and text.prefix$ BibTeX built-in functions treat
1880 braces and TeX special characters properly (like the original BibTeX
1881 functions do).
1882
1883 • Changed purify$ to replace ties and hyphens by spaces.
1884
1885 • Fixed a bug in substring$ with negative start values.
1886
1887 • Fixed .bst file grammar to allow underscores in identifiers.
1888
1889 • BibTeX name parser: ties are now treated as whitespace when splitting
1890 name parts.
1891
1892 • Implemented BibTeX-like text wrapping. The resulting .bbl output
1893 should now be byte-for-byte identical to that of BibTeX in most
1894 cases.
1895
1896 Version 0.10
1897 (released on August 24, 2009)
1898
1899 • Added support for multiple bibliography databases.
1900
1901 • Pythonic bibliography formatter: added helper functions to simplify
1902 writing BibTeX-like name formatting styles in Python. Added a tool
1903 for automatic conversion of BibTeX {ll}{, ff}-like patterns into
1904 Python.
1905
1906 • BibTeX parser: added missing characters to the caracter set of the
1907 valid identifiers.
1908
1909 • BibTeX parser: a comma is now allowed between the last field and the
1910 closing brace.
1911
1912 • BibTeX name parser: when splitting name parts into words, whitespace
1913 at brace level > 0 is now ignored.
1914
1915 • BibTeX name parser: fixed parsing of single-word lowercase names and
1916 complex von names, like in “Andrea de Leeuw van Weenen”.
1917
1918 • Fixed broken --label-style and --name-style options.
1919
1920 • Added (autogenerated) manpages.
1921
1922 • Added this changelog.
1923
1924 Version 0.9
1925 (released on August 17, 2009)
1926
1927 • Implemented \citation{*}.
1928
1929 • Implemented crossrefs.
1930
1931 • BibTeX .bib parser now supports newlines inside strings.
1932
1933 • Fixed: .bib filename from .aux file was ignored.
1934
1935 • Fixed incorrect argument passing to codecs.open().
1936
1937 • Fixed incorrect whitespace handling in the name parsing code.
1938
1939 Version 20090402
1940 (released on February 04, 2009)
1941
1942 • Fixed yet more encoding-related bugs.
1943
1944 • Cleaned up some old nasty code, updated the documentation, added more
1945 tests.
1946
1947 Version 20080918
1948 (released on September 18, 2008)
1949
1950 • Added HTML backend. The pythonic bibliography formatter can now pro‐
1951 duce LaTeX, HTML, and plaintext.
1952
1953 • BibTeXML writer now indents the resulting XML.
1954
1955 • Removed the dependency on external elementtree.
1956
1957 • Improved the interface of the pybtex-convert script. It is just con‐
1958 vert foo.bib foo.yaml now.
1959
1960 • Fixed several bugs in the BibTeX interpreter.
1961
1962 • Fixed several encoding-related bugs.
1963
1964 Version 20070513
1965 (released on May 13, 2007)
1966
1967 • Added an interpreter for the BibTeX stack language. Pybtex now sup‐
1968 ports BibTeX style files.
1969
1970 • Added a YAML bibliography format (both input and output).
1971
1972 • Improved processing of names with {braces}.
1973
1974 • Added support for @preamble to both BibTeX parser and writer.
1975
1976 • Introduced an experimental pythonic template language to make bibli‐
1977 ography formatting easier with a more functional-oriented approach.
1978
1979 • Added support for incollection entries to the experimentl pythonic
1980 bibliography style.
1981
1982 • cElementTree is now used for BibTeXML parsing, if present.
1983
1984 • Added some documentation files (finally).
1985
1986 Version 20060416
1987 (released on April 16, 2006)
1988
1989 • Added BibTeX and BibTeXML formatters for bibliography databases.
1990 Added a database conversion tool.
1991
1992 • Improved name splitting in the BibTeX parser.
1993
1994 • Locale encoding is now used by default.
1995
1996 • Added richtext.Check class to simplify formatting of optional bibli‐
1997 ography fields.
1998
1999 • Added support for booklet and inbook entry types to the experimentl
2000 pythonic bibliography style.
2001
2002 Version 20060402
2003 (released on April 2, 2006)
2004
2005 • Added initial Unicode support and input/output encodings.
2006
2007 • Introduced output backends to make bibliography styles markup-inde‐
2008 pendent. Added LaTeX and Plaintext backends.
2009
2010 • Improved BibTeXML parser, add support for pre-parsed names (<bib‐
2011 tex:first>, <bibtex:middle> and so on).
2012
2013 • Added default macros for month names to the BibTeX parser.
2014
2015 • Added an experimental richtext.Phrase (former Pack class (former
2016 Packer class)) class to make creating sentences and delimited lists
2017 easier.
2018
2019 • Added experimental support for pluggable name and label styles to the
2020 pythonic bibliogrphy formatter.
2021
2022 • Made Pybtex work on Windows by renaming aux.py to auxfile.py. Duh.
2023
2024 Version 0.1
2025 (released on March 4, 2006)
2026
2027 Initial release. This version already has a basic BibTeX .bib parser,
2028 BibTeXML parser and a proof-of-concept pythonic bibliography formatter.
2029
2031 Andrey Golovizin
2032
2034 2021, Andrey Golovizin
2035
2036
2037
2038
20390.24.0 Jan 27, 2021 PYBTEX(1)