0
# Basic Operations
1

2
Simple interface for parsing BibTeX strings and files into BibDatabase objects, and writing them back to BibTeX format. These functions provide the most straightforward way to work with BibTeX data and handle the majority of common use cases.
3

4
## Capabilities
5

6
### String Parsing
7

8
Parse BibTeX data from a string into a structured BibDatabase object. This is useful when you have BibTeX data in memory or received from an API.
9

10
```python { .api }
11
def loads(bibtex_str: str, parser=None) -> BibDatabase:
12
    """
13
    Load BibDatabase object from a BibTeX string.
14

15
    Parameters:
16
    - bibtex_str (str): Input BibTeX string to be parsed
17
    - parser (BibTexParser, optional): Custom parser to use instead of default
18

19
    Returns:
20
    BibDatabase: Parsed bibliographic database object
21

22
    Example:
23
    >>> import bibtexparser
24
    >>> bibtex_str = '@article{key, title={Example}}'
25
    >>> db = bibtexparser.loads(bibtex_str)
26
    >>> len(db.entries)
27
    1
28
    """
29
```
30

31
### File Parsing  
32

33
Parse BibTeX data directly from a file object. This is the most common way to load existing BibTeX files.
34

35
```python { .api }
36
def load(bibtex_file, parser=None) -> BibDatabase:
37
    """
38
    Load BibDatabase object from a BibTeX file.
39

40
    Parameters:
41
    - bibtex_file (file): Input file object to be parsed
42
    - parser (BibTexParser, optional): Custom parser to use instead of default
43

44
    Returns:
45
    BibDatabase: Parsed bibliographic database object
46

47
    Example:
48
    >>> import bibtexparser
49
    >>> with open('references.bib') as f:
50
    ...     db = bibtexparser.load(f)
51
    >>> print(f"Loaded {len(db.entries)} entries")
52
    """
53
```
54

55
### String Writing
56

57
Convert a BibDatabase object back to a BibTeX-formatted string. Useful for generating BibTeX output in memory.
58

59
```python { .api }
60
def dumps(bib_database: BibDatabase, writer=None) -> str:
61
    """
62
    Convert BibDatabase object to a BibTeX-formatted string.
63

64
    Parameters:
65
    - bib_database (BibDatabase): Bibliographic database object to convert
66
    - writer (BibTexWriter, optional): Custom writer to use instead of default
67

68
    Returns:
69
    str: BibTeX-formatted string
70

71
    Example:
72
    >>> import bibtexparser
73
    >>> db = bibtexparser.BibDatabase()
74
    >>> db.entries = [{'ENTRYTYPE': 'article', 'ID': 'key', 'title': 'Example'}]
75
    >>> bibtex_str = bibtexparser.dumps(db)
76
    >>> print(bibtex_str)
77
    """
78
```
79

80
### File Writing
81

82
Write a BibDatabase object directly to a file. This is the standard way to save bibliographic data.
83

84
```python { .api }
85
def dump(bib_database: BibDatabase, bibtex_file, writer=None) -> None:
86
    """
87
    Write BibDatabase object to a BibTeX file.
88

89
    Parameters:
90
    - bib_database (BibDatabase): Bibliographic database object to write
91
    - bibtex_file (file): Output file object to write to
92
    - writer (BibTexWriter, optional): Custom writer to use instead of default
93

94
    Returns:
95
    None
96

97
    Example:
98
    >>> import bibtexparser
99
    >>> db = bibtexparser.BibDatabase()
100
    >>> db.entries = [{'ENTRYTYPE': 'article', 'ID': 'key', 'title': 'Example'}]
101
    >>> with open('output.bib', 'w') as f:
102
    ...     bibtexparser.dump(db, f)
103
    """
104
```
105

106
## Usage Examples
107

108
### Complete Workflow Example
109

110
```python
111
import bibtexparser
112

113
# Read BibTeX from file
114
with open('input.bib') as bibtex_file:
115
    bib_database = bibtexparser.load(bibtex_file)
116

117
# Process entries (example: add a note to each entry)
118
for entry in bib_database.entries:
119
    entry['note'] = 'Processed by bibtexparser'
120

121
# Write back to new file  
122
with open('output.bib', 'w') as bibtex_file:
123
    bibtexparser.dump(bib_database, bibtex_file)
124
```
125

126
### String-based Processing
127

128
```python
129
import bibtexparser
130

131
bibtex_str = """
132
@article{Einstein1905,
133
    title={On the electrodynamics of moving bodies},
134
    author={Einstein, Albert},
135
    journal={Annalen der Physik},
136
    year={1905}
137
}
138
"""
139

140
# Parse from string
141
bib_database = bibtexparser.loads(bibtex_str)
142

143
# Access data
144
entry = bib_database.entries[0]
145
print(f"Title: {entry['title']}")
146
print(f"Author: {entry['author']}")
147

148
# Convert back to string
149
output_str = bibtexparser.dumps(bib_database)
150
print(output_str)
151
```
152

153
### Error Handling
154

155
```python
156
import bibtexparser
157

158
try:
159
    with open('references.bib') as bibtex_file:
160
        bib_database = bibtexparser.load(bibtex_file)
161
        print(f"Successfully loaded {len(bib_database.entries)} entries")
162
except FileNotFoundError:
163
    print("BibTeX file not found")
164
except Exception as e:
165
    print(f"Error parsing BibTeX: {e}")
166
```