1PYBTEX(1)                     Pybtex User’s Guide                    PYBTEX(1)
2
3
4

NAME

6       pybtex - Pybtex Documentation
7

COMMAND LINE INTERFACE

9Making bibliographies with pybtex
10
11Bibliography formats other then BibTeX
12
13Pythonic bibliography styles
14
15Converting bibliography databases with bibtex-convert
16
17Pretty-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

SUPPORTED FORMATS

127Bibliography formats
128
129BibTeX
130
131BibTeXML
132
133YAML
134
135Bibliography style formats
136
137Output 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
153A basic description of the BibTeX format.
154
155An 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

PYTHON API

225   Reading and writing bibliography data
226Reading bibliography data
227
228Writing bibliography data
229
230Bibliography 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
243value – Unicode string.
244
245bib_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
256value – Byte string.
257
258bib_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
269file – A file name or a file-like object.
270
271bib_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
297BibliographyData.to_string() formats  the  bibliograhy  data  into  a
298         string,
299
300BibliographyData.to_bytes()  formats the bibliograhy data into a byte
301         string,
302
303BibliographyData.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
326BibliographyData is a collection of individual  bibliography  entries
327         and some additional metadata.
328
329Entry 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
334Person 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
405file – A file name or a file-like object.
406
407bib_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
473bib_format  –  Data  format  (“bibtex”,  “yaml”,
474                              etc.).
475
476entry_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
608BibTeX engine
609
610How it works
611
612Python engine
613
614Differences from the BibTeX engine
615
616How it works
617
618Python API
619
620The base interface
621
622The BibTeXEngine class
623
624The 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
732         pybtex.richtext.Text objects that can be converted to any markup for‐
733         mat (LaTeX, 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
853bib_files_or_filenames – A list of file names or
854                              file objects.
855
856style – The name of the formatting style.
857
858citations – A list of citation keys.
859
860bib_format – The name of the  bibliography  for‐
861                              mat. The default format is bibtex.
862
863bib_encoding – Encoding of bibliography files.
864
865output_encoding  – Encoding that will be used by
866                              the output backend.
867
868bst_encoding – Encoding of the .bst file.
869
870min_crossrefs – Include cross-referenced entries
871                              after this many crossrefs. See BibTeX manual for
872                              details.
873
874output_filename – If None, the  result  will  be
875                              returned  as  a string. Else, the result will be
876                              written to the specified file.
877
878add_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
920bib_files_or_filenames – A list of file names or
921                              file objects.
922
923style – The name of the formatting style.
924
925citations – A list of citation keys.
926
927bib_format  –  The name of the bibliography for‐
928                              mat. The default format is bibtex.
929
930bib_encoding – Encoding of bibliography files.
931
932output_backend – Which output  backend  to  use.
933                              The default is latex.
934
935output_encoding  – Encoding that will be used by
936                              the output backend.
937
938bst_encoding – Encoding of the .bst file.
939
940min_crossrefs – Include cross-referenced entries
941                              after this many crossrefs. See BibTeX manual for
942                              details.
943
944output_filename – If None, the  result  will  be
945                              returned  as  a string. Else, the result will be
946                              written to the specified file.
947
948add_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
973Rich text
974
975Rich text classes
976
977Style API
978
979Template 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
1007Text
1008
1009String
1010
1011Tag
1012
1013HRef
1014
1015Protected
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 &amp; 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
1292Protected.lower(),  Protected.upper(), Protected.capitalize(),
1293                and Protected.capitalize() are  no-ops  and  just  return  the
1294                Protected object itself.
1295
1296Protected.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
1339bib_data  –  A  pybtex.database.BibliographyData
1340                              object.
1341
1342citations – 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
1393Entry points
1394
1395pybtex.database.input
1396
1397pybtex.database.output
1398
1399pybtex.backends
1400
1401pybtex.style.formatting
1402
1403pybtex.style.labels
1404
1405pybtex.style.names
1406
1407pybtex.style.sorting
1408
1409Registering plugins
1410
1411Example 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

VERSION HISTORY

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
1497         collections.OrderedDict (so it has a __delitem__).
1498
1499unsrt.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 collections.abc instead of collections.
1517
1518       • Use __iter__ instead of deprecated Element.getchildren().
1519
1520       Thanks to David Chiang, Jerry James, Jannik Schürg, Nathaniel Starkman,
1521       and Matthias Troffaes for their fixes and improvements!
1522
1523   Version 0.22.2
1524       (released on January 17, 2019)
1525
1526       • Fixed compatibility with Python 2 and older versions of Python 3.
1527
1528   Version 0.22.1
1529       (released on January 16, 2019)
1530
1531       • Fixed non-working --backend option with pybtex -l python.
1532
1533   Version 0.22.0
1534       (released on November 18, 2018)
1535
1536       • Fixed  handling  of  duplicate  fields  in .bib biles. Thanks, Jannik
1537         Schürg!
1538
1539       • BibTeX parser is now up to 10% faster on some files. Thanks,  Fabrice
1540         Benhamouda!
1541
1542       • Fixed parsing of names with \~ characters.
1543
1544       • Fixed formatting proceedings without an editor field in unsrt.py.
1545
1546       • In  case  of too many braces in a BibTeX string, PybtexSyntaxError is
1547         now raised instead of RecursionError.
1548
1549       • Dropped 2to3, made the code compatible with both Python 2 and 3  with
1550         Six.
1551
1552       • Moved tests outside of the pybtex package.
1553
1554       • Fixed searching in docs with recent versions of Sphinx.
1555
1556       • API:  renamed bibtex.BibTeXEntryIterator to bibtex.LowLevelParser for
1557         clarity.
1558
1559       • API: removed confusing usage of Person.text in tempate.names.
1560
1561       • API: Entry.fields does not automagically  look  for  cross-referenced
1562         entries anymore.
1563
1564   Version 0.21
1565       (released on January 20, 2017)
1566
1567       • BibTeX  writer  now uses latexcodec to encode characters that are not
1568         directly supported by the output encoding. Thanks, Hong Xu!
1569
1570       • HTML backend: {braced stings} are now wrapped with <span  class="bib‐
1571         tex-protected"> to enable custom CSS styling.
1572
1573unsrt.py: DOI, PubMed and Arxiv links now use HTTPS instead of HTTP.
1574
1575unsrt.py: URLs with percent characters are now formatted correctly.
1576
1577unsrt.py: short page / volume / chapter numbers are now joined with a
1578         non-breaking space, like in BibTeX.
1579
1580unsrt.py: inbook now uses the editor field if  the  author  field  is
1581         missing, like in BibTeX.
1582
1583unsrt.py: the words “volume” and “pages” in the beginning of the sen‐
1584         tence are now capitalized, like in BibTeX.
1585
1586unsrt.py: removed unnecessary period between the book title  and  the
1587         comma in inbook.
1588
1589   Version 0.20.1
1590       (released on March 17, 2016)
1591
1592       • LaTeX  backend:  fix  encoding tilde ("~") characters with newer ver‐
1593         sions of latexcodec.
1594
1595       • Fix splitting names with escaped space ("\ ") characters.
1596
1597   Version 0.20
1598       (released on March 10, 2016)
1599
1600       • YAML reader and writer now preserve the  order  of  bibliography  en‐
1601         tries.
1602
1603       • Improved URL formatting in pythonic styles.
1604
1605       • Built-in pythonic styles now support the ISBN field.
1606
1607       • Pythonic styles now treat LaTeX braces correctly:
1608
1609         • case conversion does not affect {braced substrings},
1610
1611         • braces  are  stripped  from  non-LaTeX  output:  "{P}ython" becomes
1612           "Python".
1613
1614       • 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
1618       Thanks to Hong Xu for his contributions!
1619
1620   Version 0.19
1621       (released on October 26, 2015)
1622
1623       • Added Markdown output format (contributed by Jorrit Wronski).
1624
1625       • Incorrectly formatted author and editor names now result in  warnings
1626         instead of errors, unless --strict mode is enabled.
1627
1628       • Fixed HTML escaping.
1629
1630       • Fixed parsing nested .aux files.
1631
1632       • Fixed splitting names separated by non-lowercase " and ".
1633
1634       • Fixed  line  numbers  in  error  messages  when  parsing strings with
1635         DOS/Windows line breaks.
1636
1637       • Fixed compatibility with BibTeX  when  parsing  certain  weird  “von”
1638         names.
1639
1640       • Removed excessive trailing newline from .bib output.
1641
1642       • Text wrapping now works exactly as in BibTeX.
1643
1644       • Added new API for reading and writing bibliography data.
1645
1646       • Pythonic styles: reworked and extended the rich text API.
1647
1648       • Pythonic  styles:  added  strong, i, b, tt tags, renamed the old emph
1649         tag to em.
1650
1651       • Pythonic styles: the author_year_title style now returns  ""  instead
1652         of None (fixes unorderable types error in Python 3).
1653
1654       • Ported the documentation to Sphinx.
1655
1656       Thanks  to Jorrit Wronski and Matthias Troffaes for their fixes and im‐
1657       provements!
1658
1659   Version 0.18
1660       (released on July 6, 2014)
1661
1662       • Pybtex is now fully case-insensitive (like BibTeX). As a consequence,
1663         IEEEtran styles now work correctly.
1664
1665       • Added  --preserve-case  option to pybtex-convert (default behavior is
1666         to converted all identifiers to lower case).
1667
1668       • An error is reported if two citations have the same key but different
1669         case, like in BibTeX. (Example: ddt1999 and DDT1999).
1670
1671       • Fixed  parsing  unused bibliography entries with strings containing @
1672         characters.
1673
1674entry.max$ constant is now set to 250, global.max$ is set  to  20000,
1675         like in BibTeX.
1676
1677       • Added  --strict  option  to  pybtex-convert  and pybtex-format (turns
1678         warning into errors).
1679
1680       • 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
1684         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
1688       • Added missing pybtex-format manpage.
1689
1690   Version 0.17
1691       (released on March 10, 2014)
1692
1693       • Added pybtex-format utility  for  formatting  bibliography  files  as
1694         HTML, LaTeX, and other supported human-readable formats.
1695
1696       • Added --strict command line option to pybtex (all warnings become er‐
1697         rors).
1698
1699       • Added alpha label style, and alpha and unsrtalpha formatting styles.
1700
1701       • Added support for url, eprint, doi, and pubmed fields in unsrt style.
1702
1703       • Names with hyphens are now abbreviated correctly (“Jean-Baptiste” be‐
1704         comes “J.-B.”).
1705
1706width$ now uses cmr10 font metrics, like in BibTeX. Non-latin charac‐
1707         ters are also supported.
1708
1709       • Pythonic style engine now supports @preamble commands.
1710
1711       • Warning on missing fields are now more human-readable.
1712
1713       • When writing BibTeX files, put entry key on the same line with  entry
1714         type. Fixes warnings in Jabref.
1715
1716       • When  using  multiple .bib files, macros defined in earlier files are
1717         available in subsequent ones (like in BibTeX).
1718
1719       • Fixed parsing .bst files with lines consisting of a single %  charac‐
1720         ter.
1721
1722       • Fixed  sorting  entries  without  author in author_year_title sorting
1723         style.
1724
1725       • Fixed broken CaseInsensitiveDict.get().
1726
1727CaseInsensitiveDict is now pickleable.
1728
1729       • Added  support  for  registering  plugins  at   runtime   with   pyb‐
1730         tex.plugin.register_plugin() - useful for using pybtex as a library.
1731
1732       Many  thanks  to Matthias C. M. Troffaes for his numerous fixes and im‐
1733       provements!
1734
1735   Version 0.16
1736       (released on March 17, 2012)
1737
1738       • BibTeX .bib and .bst parsers were completely rewritten. They are  now
1739         much faster and more BibTeX-compatible.
1740
1741       • Syntax errors and undefined strings in .bib files now result in warn‐
1742         ings instead of errors, like in BibTeX.
1743
1744       • Unused entries in .bib files are now skipped, like in BibTeX.
1745
1746       • The case of entry keys is now preserved (in  previous  versions  they
1747         were converted to lowercase).
1748
1749       • Pythonic style engine now supports sorting.
1750
1751       • Pythonic style engine: fixed nested optional() blocks.
1752
1753       • Fixed parsing of some names with a Last part but no von part.
1754
1755       • Fixed  processing  of brace-level-one “special characters” in purify$
1756         BibTeX built-in function.
1757
1758       • Added proper error messages on encoding errors in .bib files.
1759
1760       • The default encoding is now UTF-8 on all platforms.
1761
1762pybtex-convert now preserves the order of entries in BibTeX and  Bib‐
1763         TeXML files.
1764
1765       The following changes were contributed by Matthias C. M. Troffaes:
1766
1767       • Fixed  first_of  behavior when non-empty child is followed by a child
1768         that has a missing field.
1769
1770       • Fixed crossref lookups when key is not lower case.
1771
1772       • Completed unsrt and plain python styles: they now contain  all  entry
1773         types.
1774
1775       • Added doctree backend for rendering into a tree of docutils nodes.
1776
1777       • Added support for non-string backends.
1778
1779   Version 0.15
1780       (released on February 1, 2011)
1781
1782       • Changed license from GPL-3 to MIT.
1783
1784       • Added support for setuptools plugins.
1785
1786       • BibTeX   parser:   fixed  whitespace  normalization  in  concatenated
1787         strings.
1788
1789       • 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
1793       • BibTeX .bst interpreter now prints warnings on missing entries,  like
1794         BibTeX, instead of raising a KeyError.
1795
1796call.type$  BibTeX  built-in  function now uses default.entry for un‐
1797         known entry types, like in BibTeX.
1798
1799substring$ now accepts start=0 and returns an empty string.
1800
1801change.case$: fixed incorrect formatting  of  strings  starting  with
1802         special characters with "t" format.
1803
1804       • Fixed  abbreviation  of  names  starting  with  special characters or
1805         non-alphabetic characters.
1806
1807       • Fixed incorrect entry order and duplicated entries with \nocite{*}.
1808
1809       • Added more detailed error messages for already defined  variables  in
1810         .bst files.
1811
1812   Version 0.14.1
1813       (released on September 30, 2010)
1814
1815       • Added  missing  custom_fixers  directory to the tarball — needed only
1816         for converting the sources to Python 3.
1817
1818   Version 0.14
1819       (released on September 20, 2010)
1820
1821       • BibTeX writer: fixed quoting " (double quote) characters.
1822
1823       • BibTeX parser now produces human-readable error  messages  on  unread
1824         macros.
1825
1826       • Added error messages on missing data in .aux files.
1827
1828       • Improved performance on very long name lists.
1829
1830       • Added support for Python 3.
1831
1832   Version 0.13.2
1833       (released on February 26, 2010)
1834
1835       • BibTeX  parser:  fixed  a bug with parsing strings containing braces,
1836         like "Error in {DNA}".
1837
1838   Version 0.13.1
1839       (released on February 18, 2010)
1840
1841       • 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
1845   Version 0.13
1846       (released on February 14, 2010)
1847
1848       • Implemented --min-crossrefs option.
1849
1850       • All command line options of the original BibTeX are not supported.
1851
1852       • Pybtex now respects BSTINPUTS, BIBINPUTS and TEXMFOUTPUT  environment
1853         variables.
1854
1855       • BibTeX  bibliography  parser  now  strips  excessive  whitespace from
1856         fields, like BibTeX does.
1857
1858   Version 0.12
1859       (released on November 21, 2009)
1860
1861       • Pybtex now works correctly with \input{filename} in LaTeX files.
1862
1863       • Added a proper change.case$ BibTeX function instead of a stub.
1864
1865       • Added -e/--encoding command line option.
1866
1867       • Fixed non-working --bibtex-encoding option.
1868
1869       • Added proper error messages on missing plugins, file IO errors,  some
1870         BibTeX interpreter errors, etc.
1871
1872       • Fallback  to backslash-encoding when printing messages to the console
1873         - to make them printable regardless of the locale.
1874
1875   Version 0.11
1876       (released on September 7, 2009)
1877
1878       • 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
1882       • Changed purify$ to replace ties and hyphens by spaces.
1883
1884       • Fixed a bug in substring$ with negative start values.
1885
1886       • Fixed .bst file grammar to allow underscores in identifiers.
1887
1888       • BibTeX name parser: ties are now treated as whitespace when splitting
1889         name parts.
1890
1891       • 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
1895   Version 0.10
1896       (released on August 24, 2009)
1897
1898       • Added support for multiple bibliography databases.
1899
1900       • 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
1905       • BibTeX parser: added missing characters to the caracter  set  of  the
1906         valid identifiers.
1907
1908       • BibTeX  parser: a comma is now allowed between the last field and the
1909         closing brace.
1910
1911       • BibTeX name parser: when splitting name parts into words,  whitespace
1912         at brace level > 0 is now ignored.
1913
1914       • BibTeX  name parser: fixed parsing of single-word lowercase names and
1915         complex von names, like in “Andrea de Leeuw van Weenen”.
1916
1917       • Fixed broken --label-style and --name-style options.
1918
1919       • Added (autogenerated) manpages.
1920
1921       • Added this changelog.
1922
1923   Version 0.9
1924       (released on August 17, 2009)
1925
1926       • Implemented \citation{*}.
1927
1928       • Implemented crossrefs.
1929
1930       • BibTeX .bib parser now supports newlines inside strings.
1931
1932       • Fixed: .bib filename from .aux file was ignored.
1933
1934       • Fixed incorrect argument passing to codecs.open().
1935
1936       • Fixed incorrect whitespace handling in the name parsing code.
1937
1938   Version 20090402
1939       (released on February 04, 2009)
1940
1941       • Fixed yet more encoding-related bugs.
1942
1943       • Cleaned up some old nasty code, updated the documentation, added more
1944         tests.
1945
1946   Version 20080918
1947       (released on September 18, 2008)
1948
1949       • Added  HTML backend. The pythonic bibliography formatter can now pro‐
1950         duce LaTeX, HTML, and plaintext.
1951
1952       • BibTeXML writer now indents the resulting XML.
1953
1954       • Removed the dependency on external elementtree.
1955
1956       • Improved the interface of the pybtex-convert script. It is just  con‐
1957         vert foo.bib foo.yaml now.
1958
1959       • Fixed several bugs in the BibTeX interpreter.
1960
1961       • Fixed several encoding-related bugs.
1962
1963   Version 20070513
1964       (released on May 13, 2007)
1965
1966       • Added  an  interpreter for the BibTeX stack language. Pybtex now sup‐
1967         ports BibTeX style files.
1968
1969       • Added a YAML bibliography format (both input and output).
1970
1971       • Improved processing of names with {braces}.
1972
1973       • Added support for @preamble to both BibTeX parser and writer.
1974
1975       • Introduced an experimental pythonic template language to make  bibli‐
1976         ography formatting easier with a more functional-oriented approach.
1977
1978       • Added  support  for  incollection entries to the experimentl pythonic
1979         bibliography style.
1980
1981       • cElementTree is now used for BibTeXML parsing, if present.
1982
1983       • Added some documentation files (finally).
1984
1985   Version 20060416
1986       (released on April 16, 2006)
1987
1988       • Added BibTeX and  BibTeXML  formatters  for  bibliography  databases.
1989         Added a database conversion tool.
1990
1991       • Improved name splitting in the BibTeX parser.
1992
1993       • Locale encoding is now used by default.
1994
1995       • Added  richtext.Check class to simplify formatting of optional bibli‐
1996         ography fields.
1997
1998       • Added support for booklet and inbook entry types to  the  experimentl
1999         pythonic bibliography style.
2000
2001   Version 20060402
2002       (released on April 2, 2006)
2003
2004       • Added initial Unicode support and input/output encodings.
2005
2006       • Introduced  output  backends to make bibliography styles markup-inde‐
2007         pendent.  Added LaTeX and Plaintext backends.
2008
2009       • Improved BibTeXML parser, add support  for  pre-parsed  names  (<bib‐
2010         tex:first>, <bibtex:middle> and so on).
2011
2012       • Added default macros for month names to the BibTeX parser.
2013
2014       • Added  an  experimental  richtext.Phrase  (former  Pack class (former
2015         Packer class)) class to make creating sentences and  delimited  lists
2016         easier.
2017
2018       • Added experimental support for pluggable name and label styles to the
2019         pythonic bibliogrphy formatter.
2020
2021       • Made Pybtex work on Windows by renaming aux.py to auxfile.py. Duh.
2022
2023   Version 0.1
2024       (released on March 4, 2006)
2025
2026       Initial release. This version already has a basic BibTeX  .bib  parser,
2027       BibTeXML parser and a proof-of-concept pythonic bibliography formatter.
2028

AUTHOR

2030       Andrey Golovizin
2031
2033       2022, Andrey Golovizin
2034
2035
2036
2037
20380.24.0                           Jul 22, 2022                        PYBTEX(1)
Impressum