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

NAME

6       pybtex - Pybtex Documentation
7

COMMAND LINE INTERFACE

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
91       options to some extent.  For example,  the  --name-style  option  tells
92       Pybtex  to  use  a  different name formatting style, --abbreviate-names
93       forces Pybtex to use the abbreviated  name  format,  etc.   See  pybtex
94       --help for 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
115       human-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

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

AUTHOR

2011       Andrey Golovizin
2012
2014       2020, Andrey Golovizin
2015
2016
2017
2018
20190.23.0                           Oct 12, 2020                        PYBTEX(1)
Impressum