Skip to content

bib.bibtexparser.model

Classes

Block 

Block(start_line=None, raw=None, parser_metadata=None)

A abstract superclass of all top-level building blocks of a bibtex file.

E.g. a @string block, a @preamble block, an @entry block, a comment, etc.

Source code in pybibtexer/bib/bibtexparser/model.py 
10
11
12
13
14
15
16
17
18
19
20
def __init__(
    self,
    start_line: int | None = None,
    raw: str | None = None,
    parser_metadata: dict[str, Any] | None = None,
):
    self._start_line = start_line
    self._raw = raw
    self._parser_metadata: dict[str, Any] = {}
    if parser_metadata is not None:
        self._parser_metadata: dict[str, Any] = parser_metadata

Attributes

parser_metadata property 
parser_metadata

EXPERIMENTAL: field for middleware to store auxiliary information.

As an end-user, as long as you are not writing middleware, you probably do not need to use this field.

** Warning (experimental) ** The content of this field is undefined and may change at any time.

This field is intended for middleware to store auxiliary information. It is a key-value store, where the key is a string and the value is any python object. This allows for example to pass information between different middleware.

raw property 
raw

The raw, unmodified string (bibtex) representation of this block.

Note: Middleware does not update this field, hence, after applying middleware to a library, this field may be outdated.

start_line property 
start_line

The line number of the first line of this block in the parsed string.

Functions

get_parser_metadata 
get_parser_metadata(key)

EXPERIMENTAL: get auxiliary information stored in parser_metadata.

See attribute parser_metadata for more information.

Source code in pybibtexer/bib/bibtexparser/model.py 
53
54
55
56
57
58
def get_parser_metadata(self, key: str) -> Any | None:
    """EXPERIMENTAL: get auxiliary information stored in ``parser_metadata``.

    See attribute ``parser_metadata`` for more information.
    """
    return self._parser_metadata.get(key, None)
set_parser_metadata 
set_parser_metadata(key, value)

EXPERIMENTAL: set auxiliary information stored in parser_metadata.

See attribute parser_metadata for more information.

Source code in pybibtexer/bib/bibtexparser/model.py 
60
61
62
63
64
65
def set_parser_metadata(self, key: str, value: Any):
    """EXPERIMENTAL: set auxiliary information stored in ``parser_metadata``.

    See attribute ``parser_metadata`` for more information.
    """
    self._parser_metadata[key] = value

DuplicateBlockKeyBlock 

DuplicateBlockKeyBlock(
    key,
    previous_block,
    duplicate_block,
    start_line=None,
    raw=None,
)

Bases: ParsingFailedBlock

An error-indicating block created for blocks with keys present in the library already.

To get the block that caused this error, call block.ignore_error_block.

Source code in pybibtexer/bib/bibtexparser/model.py 
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
def __init__(
    self,
    key: str,
    previous_block: Block,
    duplicate_block: Block,
    start_line: int | None = None,
    raw: str | None = None,
):
    super().__init__(
        error=Exception(f"Duplicate entry key '{key}'"),
        start_line=start_line,
        raw=raw,
        ignore_error_block=duplicate_block,
    )
    self._key = key
    self._previous_block = previous_block

Attributes

key property writable 
key

The key of the entry, e.g. Cesar2013 in @article{Cesar2013, ...}.

previous_block property 
previous_block

A reference to a previous block with the same key.

DuplicateFieldKeyBlock 

DuplicateFieldKeyBlock(duplicate_keys, entry)

Bases: ParsingFailedBlock

An error-indicating block indicating a duplicate field key in an entry.

Source code in pybibtexer/bib/bibtexparser/model.py 
437
438
439
440
441
442
443
444
445
446
447
448
def __init__(self, duplicate_keys: set[str], entry: Entry):
    sorted_duplicate_keys = sorted(duplicate_keys)
    super().__init__(
        error=Exception(
            f"Duplicate field keys on entry: '{', '.join(sorted_duplicate_keys)}'."
            f"Note: The entry (containing duplicate) is available as `failed_block.entry`"
        ),
        start_line=entry.start_line,
        raw=entry.raw,
        ignore_error_block=entry,
    )
    self._duplicate_keys: set[str] = duplicate_keys

Attributes

duplicate_keys property 
duplicate_keys

The field-keys that occurred more than once in the entry.

Entry 

Entry(entry_type, key, fields, start_line=None, raw=None)

Bases: Block

Bibtex Blocks of the @entry type, e.g. @article{Cesar2013, ...}.

Source code in pybibtexer/bib/bibtexparser/model.py 
223
224
225
226
227
228
229
230
231
232
233
234
def __init__(
    self,
    entry_type: str,
    key: str,
    fields: list[Field],
    start_line: int | None = None,
    raw: str | None = None,
):
    super().__init__(start_line, raw)
    self._entry_type = entry_type
    self._key = key
    self._fields = fields

Attributes

entry_type property writable 
entry_type

The type of the entry, e.g. article in @article{Cesar2013, ...}.

fields property writable 
fields

The key-value attributes of an entry, as Field instances.

fields_dict property 
fields_dict

A dict of fields, with field keys as keys.

Note that with duplicate field keys, the behavior is undefined.

key property writable 
key

The key of the entry, e.g. Cesar2013 in @article{Cesar2013, ...}.

Functions

__contains__ 
__contains__(key)

Dict-mimicking in operator.

Source code in pybibtexer/bib/bibtexparser/model.py 
301
302
303
def __contains__(self, key: str) -> bool:
    """Dict-mimicking ``in`` operator."""
    return key in self.fields_dict
__delitem__ 
__delitem__(key)

Dict-mimicking index.

This serves for partial v1.x backwards compatibility, as well as for a shorthand for pop.

Source code in pybibtexer/bib/bibtexparser/model.py 
327
328
329
330
331
332
333
def __delitem__(self, key):
    """Dict-mimicking index.

    This serves for partial v1.x backwards compatibility,
    as well as for a shorthand for `pop`.
    """
    self.pop(key)
__getitem__ 
__getitem__(key)

Dict-mimicking index.

This serves for partial v1.x backwards compatibility, as well as for a shorthand for accessing field values.

Note that with duplicate field keys, the behavior is undefined.

Source code in pybibtexer/bib/bibtexparser/model.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
def __getitem__(self, key: str) -> Any:
    """Dict-mimicking index.

    This serves for partial v1.x backwards compatibility,
    as well as for a shorthand for accessing field values.

    Note that with duplicate field keys, the behavior is undefined.
    """
    if key == "ENTRYTYPE":
        return self.entry_type
    if key == "ID":
        return self.key
    return self.fields_dict[key].value
__setitem__ 
__setitem__(key, value)

Dict-mimicking index.

This serves for partial v1.x backwards compatibility, as well as for a shorthand for set_field.

Source code in pybibtexer/bib/bibtexparser/model.py 
319
320
321
322
323
324
325
def __setitem__(self, key: str, value: Any):
    """Dict-mimicking index.

    This serves for partial v1.x backwards compatibility,
    as well as for a shorthand for `set_field`.
    """
    self.set_field(Field(key, value))
get 
get(key, default=None)

Return the field with the given key, or the default value if it does not exist.

:param key: The key of the field. :param default: The value to return if the field does not exist.

Source code in pybibtexer/bib/bibtexparser/model.py 
293
294
295
296
297
298
299
def get(self, key: str, default=None) -> Field | None:
    """Return the field with the given key, or the default value if it does not exist.

    :param key: The key of the field.
    :param default: The value to return if the field does not exist.
    """
    return self.fields_dict.get(key, default)
items 
items()

Dict-mimicking, for partial v1.x backwards compatibility.

For newly written code, it's recommended to use entry.entry_type, entry.key and entry.fields instead.

Source code in pybibtexer/bib/bibtexparser/model.py 
335
336
337
338
339
340
341
def items(self):
    """Dict-mimicking, for partial v1.x backwards compatibility.

    For newly written code, it's recommended to use `entry.entry_type`,
    `entry.key` and `entry.fields` instead.
    """
    return [("ENTRYTYPE", self.entry_type), ("ID", self.key)] + [(f.key, f.value) for f in self.fields]
pop 
pop(key, default=None)

Remove and return the field with the given key.

:param key: The key of the field to remove. :param default: The value to return if the field does not exist.

Source code in pybibtexer/bib/bibtexparser/model.py 
279
280
281
282
283
284
285
286
287
288
289
290
291
def pop(self, key: str, default=None) -> Field | None:
    """Remove and return the field with the given key.

    :param key: The key of the field to remove.
    :param default: The value to return if the field does not exist.
    """
    try:
        field = self.fields_dict.pop(key)
    except KeyError:
        return default

    self._fields = [f for f in self._fields if f.key != key]
    return field
set_field 
set_field(field)

Add a new field, or replaces existing with same key.

Source code in pybibtexer/bib/bibtexparser/model.py 
271
272
273
274
275
276
277
def set_field(self, field: Field):
    """Add a new field, or replaces existing with same key."""
    if field.key in self.fields_dict:
        i = [f.key for f in self._fields].index(field.key)
        self._fields[i] = field
    else:
        self._fields.append(field)

ExplicitComment 

ExplicitComment(comment, start_line=None, raw=None)

Bases: Block

Bibtex Blocks of the @comment type, e.g. @comment{This is a comment}.

Source code in pybibtexer/bib/bibtexparser/model.py 
133
134
135
def __init__(self, comment: str, start_line: int | None = None, raw: str | None = None):
    super().__init__(start_line, raw)
    self._comment = comment

Attributes

comment property writable 
comment

The value of the comment, e.g. blabla in @comment{blabla}.

Field 

Field(key, value, start_line=None)

A field of a Bibtex entry, e.g. author = {John Doe}.

Source code in pybibtexer/bib/bibtexparser/model.py 
179
180
181
182
def __init__(self, key: str, value: Any, start_line: int | None = None):
    self._start_line = start_line
    self._key = key
    self._value = value

Attributes

key property writable 
key

The key of the field, e.g. author in author = {John Doe}.

start_line property 
start_line

The line number of the first line of this field in the originally parsed string.

value property writable 
value

The value of the field, e.g. {John Doe} in author = {John Doe}.

ImplicitComment 

ImplicitComment(comment, start_line=None, raw=None)

Bases: Block

Bibtex outside of an @{...} block, which is treated as a comment.

Source code in pybibtexer/bib/bibtexparser/model.py 
156
157
158
def __init__(self, comment: str, start_line: int | None = None, raw: str | None = None):
    super().__init__(start_line, raw)
    self._comment = comment

Attributes

comment property writable 
comment

The (possibly multi-line) comment.

MiddlewareErrorBlock 

MiddlewareErrorBlock(block, error)

Bases: ParsingFailedBlock

A block that could not be parsed due to a middleware error.

To get the block that caused this error, call block.ignore_error_block (which is the block with the middleware not or only partially applied).

Source code in pybibtexer/bib/bibtexparser/model.py 
392
393
def __init__(self, block: Block, error: Exception):
    super().__init__(start_line=block.start_line, raw=block.raw, error=error, ignore_error_block=block)

ParsingFailedBlock 

ParsingFailedBlock(
    error,
    start_line=None,
    raw=None,
    ignore_error_block=None,
)

Bases: Block

A block that could not be parsed due to some raised exception.

Source code in pybibtexer/bib/bibtexparser/model.py 
358
359
360
361
362
363
364
365
366
367
def __init__(
    self,
    error: Exception,
    start_line: int | None = None,
    raw: str | None = None,
    ignore_error_block: Block | None = None,
):
    super().__init__(start_line, raw)
    self._error = error
    self._ignore_error_block = ignore_error_block

Attributes

error property 
error

The exception that was raised during parsing.

ignore_error_block property 
ignore_error_block

The possibly faulty block when ignoring the error.

This may be None, as it may not always be possible to ignore the error. For errors caused by middleware, this is typically the block without the middleware applied.

Preamble 

Preamble(value, start_line=None, raw=None)

Bases: Block

Bibtex Blocks of the @preamble type, e.g. @preamble{This is a preamble}.

Source code in pybibtexer/bib/bibtexparser/model.py 
110
111
112
def __init__(self, value: str, start_line: int | None = None, raw: str | None = None):
    super().__init__(start_line, raw)
    self._value = value

Attributes

value property writable 
value

The value of the preamble, e.g. blabla in @preamble{blabla}.

String 

String(key, value, start_line=None, raw=None)

Bases: Block

Bibtex Blocks of the @string type, e.g. @string{me = "My Name"}.

Source code in pybibtexer/bib/bibtexparser/model.py 
77
78
79
80
def __init__(self, key: str, value: str, start_line: int | None = None, raw: str | None = None):
    super().__init__(start_line, raw)
    self._key = key
    self._value = value

Attributes

key property writable 
key

The key of the string, e.g. me in @string{me = "My Name"}.

value property writable 
value

The value of the string, e.g. "My Name" in @string{me = "My Name"}.