0
# Data Model and Database Operations
1
2
Core data structures for representing bibliographic databases including entries, comments, preambles, and string definitions. The BibDatabase class serves as the central container for all bibliographic data with support for cross-reference resolution and string expansion.
3
4
## Capabilities
5
6
### BibDatabase Class
7
8
The main container class that holds all bibliographic data and provides methods for database operations, string expansion, and cross-reference resolution.
9
10
```python { .api }
11
class BibDatabase:
12
"""
13
Bibliographic database object that follows the data structure of a BibTeX file.
14
15
Acts as the primary container for all bibliographic elements including
16
entries, comments, preambles, and string definitions.
17
"""
18
19
def __init__(self):
20
"""
21
Initialize an empty bibliographic database.
22
23
Attributes:
24
- entries (list): List of entry dictionaries (books, articles, etc.)
25
- comments (list): List of comment strings
26
- strings (OrderedDict): Dictionary of string definitions
27
- preambles (list): List of preamble strings
28
"""
29
```
30
31
### String Management
32
33
Methods for managing and expanding BibTeX string definitions, including support for common month abbreviations.
34
35
```python { .api }
36
def load_common_strings(self) -> None:
37
"""
38
Load common string definitions like month abbreviations.
39
40
Adds standard month abbreviations (jan, feb, mar, etc.) to the
41
strings dictionary for use in string interpolation.
42
"""
43
44
def expand_string(self, name: str) -> str:
45
"""
46
Expand a string definition by name.
47
48
Parameters:
49
- name (str): Name of the string to expand
50
51
Returns:
52
str: Expanded string value
53
54
Raises:
55
UndefinedString: If the string name is not defined
56
"""
57
```
58
59
### Entry Access
60
61
Methods for accessing and organizing bibliographic entries with support for different access patterns.
62
63
```python { .api }
64
def get_entry_list(self) -> list:
65
"""
66
Get a list of BibTeX entries.
67
68
Returns:
69
list: List of entry dictionaries
70
71
Note: Deprecated since v0.5.6, use entries attribute directly
72
"""
73
74
def get_entry_dict(self) -> dict:
75
"""
76
Return a dictionary of BibTeX entries keyed by entry ID.
77
78
Creates a new dictionary mapping entry IDs to entry objects.
79
Note: This method recreates the dict on each call.
80
81
Returns:
82
dict: Dictionary mapping entry IDs to entry dictionaries
83
"""
84
85
@property
86
def entries_dict(self) -> dict:
87
"""
88
Property that returns entry dictionary (calls get_entry_dict).
89
90
Returns:
91
dict: Dictionary mapping entry IDs to entry dictionaries
92
"""
93
```
94
95
### Cross-reference Resolution
96
97
Methods for resolving BibTeX cross-references and merging referenced entries.
98
99
```python { .api }
100
def add_missing_from_crossref(self) -> None:
101
"""
102
Resolve crossrefs and update entries with missing fields from referenced entries.
103
104
Processes all entries with '_crossref' fields, merging fields from the
105
referenced entry that are not already present in the referencing entry.
106
Handles circular dependencies and missing references gracefully.
107
"""
108
```
109
110
### Utility Methods
111
112
Static methods for entry sorting and processing.
113
114
```python { .api }
115
@staticmethod
116
def entry_sort_key(entry: dict, fields: tuple) -> tuple:
117
"""
118
Generate a sort key for an entry based on specified fields.
119
120
Parameters:
121
- entry (dict): Entry dictionary to generate key for
122
- fields (tuple): Field names to use for sorting
123
124
Returns:
125
tuple: Sort key tuple with string values from specified fields
126
"""
127
```
128
129
### String Data Classes
130
131
Classes for representing BibTeX string definitions and expressions with lazy evaluation and dependency tracking.
132
133
```python { .api }
134
class BibDataString:
135
"""
136
Represents a BibTeX string definition.
137
138
Enables maintaining string expressions as references to other strings
139
with lazy evaluation and dependency tracking.
140
"""
141
142
def __init__(self, bibdatabase: BibDatabase, name: str):
143
"""
144
Create a string reference.
145
146
Parameters:
147
- bibdatabase (BibDatabase): Database containing string definitions
148
- name (str): Name of the string (case-insensitive)
149
"""
150
151
def get_value(self) -> str:
152
"""
153
Get the expanded value of the string.
154
155
Returns:
156
str: Expanded string value from the database
157
158
Raises:
159
UndefinedString: If string is not defined in database
160
"""
161
162
@staticmethod
163
def expand_string(string_or_bibdatastring):
164
"""
165
Expand a string or BibDataString to its value.
166
167
Parameters:
168
- string_or_bibdatastring: String or BibDataString to expand
169
170
Returns:
171
str: Expanded string value
172
"""
173
174
class BibDataStringExpression:
175
"""
176
Represents a BibTeX string expression (concatenation of strings).
177
178
String expressions are sequences of regular strings and BibTeX strings
179
that can be concatenated together, commonly used in BibTeX for
180
combining month abbreviations with years or other string values.
181
"""
182
183
def __init__(self, expression: list):
184
"""
185
Create a string expression.
186
187
Parameters:
188
- expression (list): List of strings and BibDataString objects
189
"""
190
191
def get_value(self) -> str:
192
"""
193
Get the expanded value by concatenating all expression components.
194
195
Returns:
196
str: Concatenated and expanded string value
197
"""
198
199
def apply_on_strings(self, fun: callable) -> None:
200
"""
201
Apply a function to all regular strings in the expression.
202
203
Parameters:
204
- fun (callable): Function to apply to string components
205
"""
206
207
@staticmethod
208
def expand_if_expression(string_or_expression):
209
"""
210
Expand a string or expression to its value.
211
212
Parameters:
213
- string_or_expression: String or BibDataStringExpression to expand
214
215
Returns:
216
str: Expanded string value
217
"""
218
219
@staticmethod
220
def expression_if_needed(tokens: list):
221
"""
222
Create expression only if tokens represent a complex expression.
223
224
Parameters:
225
- tokens (list): List of parsed tokens
226
227
Returns:
228
str or BibDataStringExpression: Simple string or complex expression
229
"""
230
```
231
232
### Utility Functions
233
234
Functions for working with text and string expressions in bibliographic data.
235
236
```python { .api }
237
def as_text(text_string_or_expression) -> str:
238
"""
239
Convert text, string, or expression to plain text.
240
241
Parameters:
242
- text_string_or_expression: Text, BibDataString, or BibDataStringExpression
243
244
Returns:
245
str: Plain text representation
246
"""
247
```
248
249
### Constants
250
251
Predefined constants for standard BibTeX types and common string definitions.
252
253
```python { .api }
254
STANDARD_TYPES: set
255
# Standard BibTeX entry types: article, book, booklet, conference, inbook,
256
# incollection, inproceedings, manual, mastersthesis, misc, phdthesis,
257
# proceedings, techreport, unpublished
258
259
COMMON_STRINGS: dict
260
# Common month abbreviations: jan->January, feb->February, etc.
261
```
262
263
### Exceptions
264
265
Exception classes for handling errors in string processing and database operations.
266
267
```python { .api }
268
class UndefinedString(KeyError):
269
"""
270
Exception raised when attempting to expand an undefined string.
271
272
Inherits from KeyError for compatibility with dictionary-like access patterns.
273
"""
274
pass
275
```
276
277
## Usage Examples
278
279
### Basic Database Operations
280
281
```python
282
from bibtexparser.bibdatabase import BibDatabase
283
284
# Create a new database
285
db = BibDatabase()
286
287
# Add entries
288
db.entries.append({
289
'ENTRYTYPE': 'article',
290
'ID': 'example2023',
291
'title': 'Example Article',
292
'author': 'John Doe',
293
'year': '2023'
294
})
295
296
# Add comments and preambles
297
db.comments.append('This is a comment')
298
db.preambles.append('This bibliography was generated automatically')
299
300
# Access entries
301
print(f"Database contains {len(db.entries)} entries")
302
for entry in db.entries:
303
print(f"{entry['ID']}: {entry.get('title', 'No title')}")
304
```
305
306
### String Definitions and Expansion
307
308
```python
309
from bibtexparser.bibdatabase import BibDatabase
310
311
db = BibDatabase()
312
313
# Load common month abbreviations
314
db.load_common_strings()
315
316
# Add custom string definitions
317
db.strings['myjournal'] = 'Journal of Example Research'
318
db.strings['myvolume'] = '42'
319
320
# Expand strings
321
print(db.expand_string('jan')) # Output: January
322
print(db.expand_string('myjournal')) # Output: Journal of Example Research
323
324
# Access all strings
325
for name, value in db.strings.items():
326
print(f"{name} = {value}")
327
```
328
329
### Cross-reference Resolution
330
331
```python
332
# Create entries with cross-references
333
db.entries = [
334
{
335
'ENTRYTYPE': 'inproceedings',
336
'ID': 'paper1',
337
'title': 'Example Paper',
338
'author': 'Jane Smith',
339
'_crossref': 'conf2023' # Reference to conference
340
},
341
{
342
'ENTRYTYPE': 'proceedings',
343
'ID': 'conf2023',
344
'title': 'Proceedings of Example Conference',
345
'year': '2023',
346
'publisher': 'Example Publisher'
347
}
348
]
349
350
# Resolve cross-references
351
db.add_missing_from_crossref()
352
353
# The paper1 entry now has year and publisher from conf2023
354
paper = db.get_entry_dict()['paper1']
355
print(paper['year']) # Output: 2023
356
print(paper['publisher']) # Output: Example Publisher
357
print(paper['_FROM_CROSSREF']) # Fields added from crossref
358
```
359
360
### Entry Dictionary Access
361
362
```python
363
# Access entries by ID
364
entries_dict = db.get_entry_dict()
365
specific_entry = entries_dict.get('example2023')
366
367
if specific_entry:
368
print(f"Found entry: {specific_entry['title']}")
369
370
# Or use the property
371
entry = db.entries_dict['example2023']
372
```
373
374
### Working with String Expressions
375
376
```python
377
from bibtexparser.bibdatabase import BibDataString, BibDataStringExpression
378
379
# Create string references
380
month_ref = BibDataString(db, 'jan')
381
year_string = '2023'
382
383
# Create expression combining month and year
384
expression = BibDataStringExpression([month_ref, ' ', year_string])
385
print(expression.get_value()) # Output: January 2023
386
387
# Apply transformations to strings only
388
expression.apply_on_strings(str.upper)
389
print(expression.get_value()) # Output: January 2023 (month ref unchanged)
390
```