bibtexparser 2.0.0b8__tar.gz → 2.0.0b9__tar.gz

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bibtexparser
-Version: 2.0.0b8
+Version: 2.0.0b9
 Summary: Bibtex parser for python 3
 Home-page: https://github.com/sciunto-org/python-bibtexparser
 Author: Michael Weiss and other contributors
@@ -10,12 +10,17 @@ Maintainer-email: code@mweiss.ch
 License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pylatexenc>=2.10
+Requires-Dist: pylatexenc~=2.10
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-xdist; extra == "test"
@@ -23,12 +28,26 @@ Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: jupyter; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # python-bibtexparser v2
 
-Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adaption.
+Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adoption.
 
-Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is an early beta, and does not contain all features of v1**. Install v2 using pip:
+Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is still in beta stage, and does not contain all features of v1**. Install v2 using pip:
 
 ```bash
 pip install bibtexparser --pre
@@ -87,7 +106,7 @@ bib_database = bibtexparser.parse_string(bibtex_string,
 
 # Let's transform it back to a bibtex_string.
 new_bibtex_string = bibtexparser.write_string(bib_database,
-    # Revert aboves transfomration
+    # Revert above transformation
     prepend_middleware=[MergeNameParts(), MergeCoAuthors()]
 )
 ```
@@ -102,14 +121,14 @@ Consult the documentation for a list of available middleware, parsing options an
 The architecture consists of the following components:
 
 #### Library
-Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preamples and their metadata (e.g. order).
+Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preambles and their metadata (e.g. order).
 
 #### A Splitter
 Splits a bibtex string into basic blocks (Entry, String, Preamble, ...), with correspondingly split content (e.g. fields on Entry, key-value on String, ...).
 The splitter aims to be forgiving when facing invalid bibtex: A line starting with a block definition (``@....``) ends the previous block, even if not yet every bracket is closed, failing the parsing of the previous block. Correspondingly, one block type is "ParsingFailedBlock".
 
 #### Middleware
-Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resoling crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, no not mutate their input, but return a modified copy.
+Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resolving crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, do not mutate their input, but return a modified copy.
 
 #### Writer
 Writes the content of a bibtex library to a ``.bib`` file. Optional formatting parameters can be passed using a corresponding dedicated data structure.

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/README.md

@@ -1,8 +1,8 @@
 # python-bibtexparser v2
 
-Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adaption.
+Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adoption.
 
-Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is an early beta, and does not contain all features of v1**. Install v2 using pip:
+Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is still in beta stage, and does not contain all features of v1**. Install v2 using pip:
 
 ```bash
 pip install bibtexparser --pre
@@ -61,7 +61,7 @@ bib_database = bibtexparser.parse_string(bibtex_string,
 
 # Let's transform it back to a bibtex_string.
 new_bibtex_string = bibtexparser.write_string(bib_database,
-    # Revert aboves transfomration
+    # Revert above transformation
     prepend_middleware=[MergeNameParts(), MergeCoAuthors()]
 )
 ```
@@ -76,14 +76,14 @@ Consult the documentation for a list of available middleware, parsing options an
 The architecture consists of the following components:
 
 #### Library
-Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preamples and their metadata (e.g. order).
+Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preambles and their metadata (e.g. order).
 
 #### A Splitter
 Splits a bibtex string into basic blocks (Entry, String, Preamble, ...), with correspondingly split content (e.g. fields on Entry, key-value on String, ...).
 The splitter aims to be forgiving when facing invalid bibtex: A line starting with a block definition (``@....``) ends the previous block, even if not yet every bracket is closed, failing the parsing of the previous block. Correspondingly, one block type is "ParsingFailedBlock".
 
 #### Middleware
-Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resoling crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, no not mutate their input, but return a modified copy.
+Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resolving crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, do not mutate their input, but return a modified copy.
 
 #### Writer
 Writes the content of a bibtex library to a ``.bib`` file. Optional formatting parameters can be passed using a corresponding dedicated data structure.

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/__init__.py

@@ -8,4 +8,4 @@ from bibtexparser.entrypoint import write_string
 from bibtexparser.library import Library
 from bibtexparser.writer import BibtexFormat
 
-__version__ = "2.0.0b8"
+__version__ = "2.0.0b9"

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/entrypoint.py

@@ -1,3 +1,4 @@
+import codecs
 import warnings
 from typing import Iterable
 from typing import List
@@ -20,9 +21,9 @@ def _build_parse_stack(
 ) -> List[Middleware]:
     if parse_stack is not None and append_middleware is not None:
         raise ValueError(
-            "Provided both parse_stack and append_middleware."
-            "Only one should be provided."
-            "(append_middleware should only be used with the default parse_stack,"
+            "Provided both parse_stack and append_middleware. "
+            "Only one should be provided. "
+            "(append_middleware should only be used with the default parse_stack, "
             "i.e., when the passed parse_stack is None.)"
         )
 
@@ -50,10 +51,10 @@ def _build_unparse_stack(
 ) -> List[Middleware]:
     if unparse_stack is not None and prepend_middleware is not None:
         raise ValueError(
-            "Provided both parse_stack and append_middleware."
-            "Only one should be provided."
-            "(prepend_middleware should only be used with the default parse_stack,"
-            "i.e., when the passed parse_stack is None.)"
+            "Provided both unparse_stack and prepend_middleware. "
+            "Only one should be provided. "
+            "(prepend_middleware should only be used with the default unparse_stack, "
+            "i.e., when the passed unparse_stack is None.)"
         )
 
     if unparse_stack is None:
@@ -74,6 +75,52 @@ def _build_unparse_stack(
     return list(prepend_middleware) + list(unparse_stack)
 
 
+def _handle_deprecated_write_params(
+    unparse_stack: Optional[Iterable[Middleware]],
+    prepend_middleware: Optional[Iterable[Middleware]],
+    kwargs: dict,
+    function_name: str,
+) -> tuple[Optional[Iterable[Middleware]], Optional[Iterable[Middleware]]]:
+    """Handle deprecated parameter names for write functions.
+
+    :param unparse_stack: Current unparse_stack value
+    :param prepend_middleware: Current prepend_middleware value
+    :param kwargs: Dictionary of keyword arguments to check for deprecated params
+    :param function_name: Name of the calling function (for error messages)
+    :return: Tuple of (unparse_stack, prepend_middleware) with deprecated values migrated
+    """
+    if "parse_stack" in kwargs:
+        warnings.warn(
+            "Parameter 'parse_stack' is deprecated. Use 'unparse_stack' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        if unparse_stack is not None:
+            raise ValueError(
+                "Cannot provide both 'parse_stack' (deprecated) and 'unparse_stack'. "
+                "Use 'unparse_stack' instead."
+            )
+        unparse_stack = kwargs.pop("parse_stack")
+
+    if "append_middleware" in kwargs:
+        warnings.warn(
+            "Parameter 'append_middleware' is deprecated. Use 'prepend_middleware' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        if prepend_middleware is not None:
+            raise ValueError(
+                "Cannot provide both 'append_middleware' (deprecated) and 'prepend_middleware'. "
+                "Use 'prepend_middleware' instead."
+            )
+        prepend_middleware = kwargs.pop("append_middleware")
+
+    if kwargs:
+        raise TypeError(f"{function_name}() got unexpected keyword arguments: {', '.join(kwargs)}")
+
+    return unparse_stack, prepend_middleware
+
+
 def parse_string(
     bibtex_str: str,
     parse_stack: Optional[Iterable[Middleware]] = None,
@@ -125,7 +172,13 @@ def parse_file(
 
     :param encoding: Encoding of the .bib file. Default encoding is ``"UTF-8"``.
     :return: Library: Parsed BibTeX library
+    :raises LookupError: If the specified encoding is not recognized.
     """
+    try:
+        codecs.lookup(encoding)
+    except LookupError:
+        raise LookupError(f"Unknown encoding: {encoding!r}")
+
     with open(path, encoding=encoding) as f:
         bibtex_str = f.read()
         return parse_string(
@@ -136,27 +189,39 @@ def parse_file(
 def write_file(
     file: Union[str, TextIO],
     library: Library,
-    parse_stack: Optional[Iterable[Middleware]] = None,
-    append_middleware: Optional[Iterable[Middleware]] = None,
+    unparse_stack: Optional[Iterable[Middleware]] = None,
+    prepend_middleware: Optional[Iterable[Middleware]] = None,
     bibtex_format: Optional[BibtexFormat] = None,
+    encoding: str = "UTF-8",
+    **kwargs,
 ) -> None:
     """Write a BibTeX database to a file.
 
     :param file: File to write to. Can be a file name or a file object.
     :param library: BibTeX database to serialize.
-    :param parse_stack: List of middleware to apply to the database before writing.
+    :param unparse_stack: List of middleware to apply to the database before writing.
                         If None, a default stack will be used.
-    :param append_middleware: List of middleware to append to the default stack.
-                        Only applicable if `parse_stack` is None.
-    :param bibtex_format: Customized BibTeX format to use (optional)."""
+    :param prepend_middleware: List of middleware to prepend to the default stack.
+                        Only applicable if `unparse_stack` is None.
+    :param bibtex_format: Customized BibTeX format to use (optional).
+    :param encoding: Encoding of the .bib file. Default encoding is ``"UTF-8"``.
+
+    .. deprecated:: (next version)
+        Parameters 'parse_stack' and 'append_middleware' are deprecated, will be deleted soon.
+        Use 'unparse_stack' and 'prepend_middleware' instead.
+    """
+    unparse_stack, prepend_middleware = _handle_deprecated_write_params(
+        unparse_stack, prepend_middleware, kwargs, "write_file"
+    )
+
     bibtex_str = write_string(
         library=library,
-        unparse_stack=parse_stack,
-        prepend_middleware=append_middleware,
+        unparse_stack=unparse_stack,
+        prepend_middleware=prepend_middleware,
         bibtex_format=bibtex_format,
     )
     if isinstance(file, str):
-        with open(file, "w") as f:
+        with open(file, "w", encoding=encoding) as f:
             f.write(bibtex_str)
     else:
         file.write(bibtex_str)
@@ -167,6 +232,7 @@ def write_string(
     unparse_stack: Optional[Iterable[Middleware]] = None,
     prepend_middleware: Optional[Iterable[Middleware]] = None,
     bibtex_format: Optional["BibtexFormat"] = None,
+    **kwargs,
 ) -> str:
     """Serialize a BibTeX database to a string.
 
@@ -174,9 +240,17 @@ def write_string(
     :param unparse_stack: List of middleware to apply to the database before writing.
                         If None, a default stack will be used.
     :param prepend_middleware: List of middleware to prepend to the default stack.
-                        Only applicable if `parse_stack` is None.
+                        Only applicable if `unparse_stack` is None.
     :param bibtex_format: Customized BibTeX format to use (optional).
+
+    .. deprecated:: (next version)
+        Parameters 'parse_stack' and 'append_middleware' are deprecated.
+        Use 'unparse_stack' and 'prepend_middleware' instead.
     """
+    unparse_stack, prepend_middleware = _handle_deprecated_write_params(
+        unparse_stack, prepend_middleware, kwargs, "write_string"
+    )
+
     middleware: Middleware
     for middleware in _build_unparse_stack(unparse_stack, prepend_middleware):
         library = middleware.transform(library=library)

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/library.py

@@ -107,18 +107,22 @@ class Library:
     def _cast_to_duplicate(
         prev_block_with_same_key: Union[Entry, String], duplicate: Union[Entry, String]
     ):
-        assert isinstance(prev_block_with_same_key, type(duplicate)) or isinstance(
-            duplicate, type(prev_block_with_same_key)
-        ), (
-            "Internal BibtexParser Error. Duplicate blocks share no common type."
-            f"Found {type(prev_block_with_same_key)} and {type(duplicate)}, but both should be"
-            f"either instance of String or instance of Entry."
-            f"Please report this issue at the bibtexparser issue tracker.",
-        )
-
-        assert (
-            prev_block_with_same_key.key == duplicate.key
-        ), "Internal BibtexParser Error. Duplicate blocks have different keys."
+        if not (
+            isinstance(prev_block_with_same_key, type(duplicate))
+            or isinstance(duplicate, type(prev_block_with_same_key))
+        ):
+            raise ValueError(
+                "Internal BibtexParser Error. Duplicate blocks share no common type. "
+                f"Found {type(prev_block_with_same_key)} and {type(duplicate)}, but both should be "
+                "either instance of String or instance of Entry. "
+                "Please report this issue at the bibtexparser issue tracker."
+            )
+
+        if prev_block_with_same_key.key != duplicate.key:
+            raise ValueError(
+                "Internal BibtexParser Error. Duplicate blocks have different keys. "
+                "Please report this issue at the bibtexparser issue tracker."
+            )
 
         return DuplicateBlockKeyBlock(
             start_line=duplicate.start_line,

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/middlewares/latex_encoding.py

@@ -102,10 +102,15 @@ class LatexEncodingMiddleware(_PyStringTransformerMiddleware):
 
         if encoder is not None and (keep_math is not None or enclose_urls is not None):
             raise ValueError(
-                "Cannot specify both encoder and keep_math or enclose_urls."
+                "Cannot specify both encoder and keep_math or enclose_urls. "
                 "If you want to use a custom encoder, you have to specify it completely."
             )
 
+        if encoder is not None and not isinstance(encoder, UnicodeToLatexEncoder):
+            raise TypeError(
+                f"encoder must be a UnicodeToLatexEncoder instance, got {type(encoder).__name__}"
+            )
+
         # Defaults (not specified as defaults in args,
         #   to make sure we can identify if they were specified)
         keep_math = keep_math if keep_math is not None else True
@@ -166,12 +171,17 @@ class LatexDecodingMiddleware(_PyStringTransformerMiddleware):
 
         if decoder is not None and (keep_braced_groups is not None or keep_math_mode is not None):
             raise ValueError(
-                "Cannot specify both encoder and one of "
-                "`keep_braced_groups` or `keep_braced_groups`."
-                "If you want to use a custom encoder, "
+                "Cannot specify both decoder and one of "
+                "`keep_braced_groups` or `keep_math_mode`. "
+                "If you want to use a custom decoder, "
                 "you have to specify it completely."
             )
 
+        if decoder is not None and not isinstance(decoder, LatexNodes2Text):
+            raise TypeError(
+                f"decoder must be a LatexNodes2Text instance, got {type(decoder).__name__}"
+            )
+
         # Defaults (not specified as defaults in args,
         #   to make sure we can identify if they were specified)
         keep_braced_groups = keep_braced_groups if keep_braced_groups is not None else False

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/middlewares/names.py

@@ -9,6 +9,7 @@ import dataclasses
 from typing import List
 from typing import Literal
 from typing import Tuple
+from typing import Union
 
 from bibtexparser.model import Block
 from bibtexparser.model import Entry
@@ -73,7 +74,7 @@ class SeparateCoAuthors(_NameTransformerMiddleware):
         return "separate_coauthors"
 
     # docstr-coverage: inherited
-    def _transform_field_value(self, name) -> List[str]:
+    def _transform_field_value(self, name: str) -> List[str]:
         return split_multiple_persons_names(name)
 
 
@@ -86,7 +87,7 @@ class MergeCoAuthors(_NameTransformerMiddleware):
         return "merge_coauthors"
 
     # docstr-coverage: inherited
-    def _transform_field_value(self, name):
+    def _transform_field_value(self, name: Union[List[str], str]) -> str:
         if isinstance(name, list):
             return " and ".join(name)
         return name
@@ -160,12 +161,12 @@ class SplitNameParts(_NameTransformerMiddleware):
     def metadata_key(cls) -> str:
         return "split_name_parts"
 
-    def _transform_field_value(self, name) -> List[NameParts]:
+    def _transform_field_value(self, name: List[str]) -> List[NameParts]:
         if not isinstance(name, list):
             raise ValueError(
                 "Expected a list of strings, got {}. "
-                "Make sure to use `SeparateCoAuthors` middleware"
-                "before using `SplitNameParts` middleware".format(name)
+                "Make sure to use `SeparateCoAuthors` middleware "
+                "before using `SplitNameParts` middleware.".format(name)
             )
 
         return [parse_single_name_into_parts(n) for n in name]
@@ -195,8 +196,8 @@ class MergeNameParts(_NameTransformerMiddleware):
     def metadata_key(cls) -> str:
         return "merge_name_parts"
 
-    def _transform_field_value(self, name) -> List[str]:
-        if not isinstance(name, list) and all(isinstance(n, NameParts) for n in name):
+    def _transform_field_value(self, name: List[NameParts]) -> List[str]:
+        if not (isinstance(name, list) and all(isinstance(n, NameParts) for n in name)):
             raise ValueError(f"Expected a list of NameParts, got {name}. ")
 
         if self.style == "last":
@@ -207,7 +208,7 @@ class MergeNameParts(_NameTransformerMiddleware):
             raise ValueError(f"""Expected "first" or "last" style, got {self.style}. """)
 
 
-def parse_single_name_into_parts(name, strict=True):
+def parse_single_name_into_parts(name: str, strict: bool = True) -> NameParts:
     """
     Parse a name into its constituent parts: First, von, Last, and Jr.
 
@@ -502,7 +503,7 @@ def parse_single_name_into_parts(name, strict=True):
     return parts
 
 
-def split_multiple_persons_names(names):
+def split_multiple_persons_names(names: str) -> List[str]:
     """
     Splits a string of multiple names.
 

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/model.py

@@ -4,10 +4,11 @@ from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Set
+from typing import Tuple
 
 
 class Block(abc.ABC):
-    """A abstract superclass of all top-level building blocks of a bibtex file.
+    """An 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.
     """
@@ -67,7 +68,7 @@ class Block(abc.ABC):
         See attribute ``parser_metadata`` for more information."""
         self._parser_metadata[key] = value
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         # make sure they have the same type and same content
         return (
             isinstance(other, self.__class__)
@@ -108,10 +109,10 @@ class String(Block):
     def value(self, value: str):
         self._value = value
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"String (line: {self.start_line}, key: `{self.key}`): `{self.value}`"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"String(key=`{self.key}`, value=`{self.value}`, "
             f"start_line={self.start_line}, raw=`{self.raw}`)"
@@ -134,10 +135,10 @@ class Preamble(Block):
     def value(self, value: str):
         self._value = value
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"Preamble (line: {self.start_line}): `{self.value}`"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"Preamble(value=`{self.value}`, " f"start_line={self.start_line}, raw=`{self.raw}`)"
 
 
@@ -157,10 +158,10 @@ class ExplicitComment(Block):
     def comment(self, value: str):
         self._comment = value
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"ExplicitComment (line: {self.start_line}): `{self.comment}`"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"ExplicitComment(comment=`{self.comment}`, "
             f"start_line={self.start_line}, raw=`{self.raw}`)"
@@ -183,10 +184,10 @@ class ImplicitComment(Block):
     def comment(self, value: str):
         self._comment = value
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"ImplicitComment (line: {self.start_line}): `{self.comment}`"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"ImplicitComment(comment=`{self.comment}`, "
             f"start_line={self.start_line}, raw=`{self.raw}`)"
@@ -224,7 +225,7 @@ class Field:
         """The line number of the first line of this field in the originally parsed string."""
         return self._start_line
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         # make sure they have the same type and same content
         return (
             isinstance(other, self.__class__)
@@ -232,10 +233,10 @@ class Field:
             and self.__dict__ == other.__dict__
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"Field (line: {self.start_line}, key: `{self.key}`): `{self.value}`"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"Field(key=`{self.key}`, value=`{self.value}`, " f"start_line={self.start_line})"
 
 
@@ -256,7 +257,7 @@ class Entry(Block):
         self._fields = fields
 
     @property
-    def entry_type(self):
+    def entry_type(self) -> str:
         """The type of the entry, e.g. ``article`` in ``@article{Cesar2013, ...}``."""
         return self._entry_type
 
@@ -265,7 +266,7 @@ class Entry(Block):
         self._entry_type = value
 
     @property
-    def key(self):
+    def key(self) -> str:
         """The key of the entry, e.g. ``Cesar2013`` in ``@article{Cesar2013, ...}``."""
         return self._key
 
@@ -343,7 +344,7 @@ class Entry(Block):
         """
         self.set_field(Field(key, value))
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: str) -> None:
         """Dict-mimicking index.
 
         This serves for partial v1.x backwards compatibility,
@@ -351,7 +352,7 @@ class Entry(Block):
         """
         self.pop(key)
 
-    def items(self):
+    def items(self) -> List[Tuple[str, Any]]:
         """Dict-mimicking, for partial v1.x backwards compatibility.
 
         For newly written code, it's recommended to use `entry.entry_type`,
@@ -361,12 +362,12 @@ class Entry(Block):
             ("ID", self.key),
         ] + [(f.key, f.value) for f in self.fields]
 
-    def __str__(self):
+    def __str__(self) -> str:
         lines = [f"Entry (line: {self.start_line}, type: `{self.entry_type}`, key: `{self.key}`):"]
         lines.extend([f"\t`{f.key}` = `{f.value}`" for f in self.fields])
         return "\n".join(lines)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"Entry(entry_type=`{self.entry_type}`, key=`{self.key}`, "
             f"fields=`{self.fields.__repr__()}`, start_line={self.start_line})"

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser/splitter.py

@@ -46,7 +46,7 @@ class Splitter:
 
         self._reset_block_status(current_char_index=0)
 
-    def _reset_block_status(self, current_char_index):
+    def _reset_block_status(self, current_char_index: int) -> None:
         self._open_brackets = 0
         self._is_quote_open = False
         self._expected_next: Optional[List[str]] = None
@@ -57,6 +57,24 @@ class Splitter:
         self._implicit_comment_start_line = self._current_line
         self._implicit_comment_start: Optional[int] = current_char_index
 
+    def _is_at_line_start(self, pos: int) -> bool:
+        """Check if position is at the start of a line (after optional whitespace).
+
+        This is used to determine whether an @ sign should be treated as a new
+        block start (for error recovery) or as content within a field value.
+        We only want to abort parsing and start a new block if the @ is at the
+        beginning of a line, to avoid false positives with @ signs in content.
+        """
+        # Scan backwards from pos to find either newline or non-whitespace
+        for i in range(pos - 1, -1, -1):
+            char = self.bibstr[i]
+            if char == "\n":
+                return True
+            elif not char.isspace():
+                return False
+        # Start of string counts as line start
+        return True
+
     def _end_implicit_comment(self, end_char_index) -> Optional[ImplicitComment]:
         if self._implicit_comment_start is None:
             return  # No implicit comment started
@@ -122,7 +140,11 @@ class Splitter:
                     return m.start()
                 else:
                     num_additional_brackets -= 1
-            elif m.group(0).startswith("@"):
+            elif m.group(0).startswith("@") and self._is_at_line_start(m.start()):
+                # Only abort if the @ is at the start of a line.
+                # This allows @ signs in field values (e.g., "LeQua @ {CLEF}")
+                # while still providing error recovery when a new block starts
+                # on a new line within an unclosed block.
                 self._unaccepted_mark = m
                 raise BlockAbortedException(
                     abort_reason=f"Unexpected block start: `{m.group(0)}`. "
@@ -131,7 +153,7 @@ class Splitter:
                 )
 
     def _move_to_comma_or_closing_curly_bracket(
-        self, currently_quote_escaped=False, num_open_curls=0
+        self, currently_quote_escaped: bool = False, num_open_curls: int = 0
     ) -> int:
         """Index of the end of the field, taking quote-escape into account."""
 
@@ -151,6 +173,24 @@ class Splitter:
 
             # Handle "escape" characters
             if next_mark.group(0) == '"' and not num_open_curls > 0:
+                # Check for {"} escape sequence when inside quotes (issue #487).
+                # Per https://tug.ctan.org/info/bibtex/tamethebeast/ttb_en.pdf,
+                # {"} represents a literal quote in a quoted field.
+                # We verify this by checking:
+                # 1. We're inside quotes
+                # 2. The " is surrounded by { and }
+                # 3. There's more content after the } (i.e., pos+2 is in bounds)
+                #    This distinguishes {"} escapes from cases like @article{"}
+                #    where " closes the field and } closes the entry.
+                if currently_quote_escaped:
+                    pos = next_mark.start()
+                    if (
+                        pos > 0
+                        and pos + 2 < len(self.bibstr)
+                        and self.bibstr[pos - 1] == "{"
+                        and self.bibstr[pos + 1] == "}"
+                    ):
+                        continue
                 currently_quote_escaped = not currently_quote_escaped
                 continue
             elif next_mark.group(0) == "{" and not currently_quote_escaped:
@@ -169,8 +209,11 @@ class Splitter:
                 self._unaccepted_mark = next_mark
                 return next_mark.start()
 
-            # Sanity-check: If new block is starting, we abort
-            elif next_mark.group(0).startswith("@"):
+            # Sanity-check: If new block is starting at line start, we abort.
+            # We only abort if the @ is at the start of a line to allow @ signs
+            # in field values (e.g., "LeQua @ {CLEF}") while still providing
+            # error recovery when a new block starts on a new line.
+            elif next_mark.group(0).startswith("@") and self._is_at_line_start(next_mark.start()):
                 self._unaccepted_mark = next_mark
 
                 if currently_quote_escaped:
@@ -291,8 +334,8 @@ class Splitter:
                         f"due to syntactical error in bibtex:\n {e.abort_reason}"
                     )
                     logger.info(
-                        "We will try to continue parsing, but this might lead to unexpected results."
-                        "The failed block will be stored in the `failed_blocks`of the library."
+                        "We will try to continue parsing, but this might lead to unexpected results. "
+                        "The failed block will be stored in the `failed_blocks` of the library."
                     )
                     library.add(
                         ParsingFailedBlock(
@@ -308,14 +351,14 @@ class Splitter:
                         "python-bibtexparser detected an invalid state. Please report this bug."
                     )
                     logger.error(e.message)
-                    raise e
-                except Exception as e:
-                    # For unknown exeptions, we want to fail hard and get the info in our issue tracker.
+                    raise
+                except Exception:
+                    # For unknown exceptions, we want to fail hard and get the info in our issue tracker.
                     logger.error(
-                        f"Unexpected exception while parsing `{m_val}` block (line {start_line})"
+                        f"Unexpected exception while parsing `{m_val}` block (line {start_line}). "
                         "Please report this bug."
                     )
-                    raise e
+                    raise
 
                 self._reset_block_status(current_char_index=self._current_char_index + 1)
             else:

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bibtexparser
-Version: 2.0.0b8
+Version: 2.0.0b9
 Summary: Bibtex parser for python 3
 Home-page: https://github.com/sciunto-org/python-bibtexparser
 Author: Michael Weiss and other contributors
@@ -10,12 +10,17 @@ Maintainer-email: code@mweiss.ch
 License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pylatexenc>=2.10
+Requires-Dist: pylatexenc~=2.10
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-xdist; extra == "test"
@@ -23,12 +28,26 @@ Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: jupyter; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # python-bibtexparser v2
 
-Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adaption.
+Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adoption.
 
-Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is an early beta, and does not contain all features of v1**. Install v2 using pip:
+Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is still in beta stage, and does not contain all features of v1**. Install v2 using pip:
 
 ```bash
 pip install bibtexparser --pre
@@ -87,7 +106,7 @@ bib_database = bibtexparser.parse_string(bibtex_string,
 
 # Let's transform it back to a bibtex_string.
 new_bibtex_string = bibtexparser.write_string(bib_database,
-    # Revert aboves transfomration
+    # Revert above transformation
     prepend_middleware=[MergeNameParts(), MergeCoAuthors()]
 )
 ```
@@ -102,14 +121,14 @@ Consult the documentation for a list of available middleware, parsing options an
 The architecture consists of the following components:
 
 #### Library
-Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preamples and their metadata (e.g. order).
+Reflects the contents of a parsed bibtex files, including all comments, entries, strings, preambles and their metadata (e.g. order).
 
 #### A Splitter
 Splits a bibtex string into basic blocks (Entry, String, Preamble, ...), with correspondingly split content (e.g. fields on Entry, key-value on String, ...).
 The splitter aims to be forgiving when facing invalid bibtex: A line starting with a block definition (``@....``) ends the previous block, even if not yet every bracket is closed, failing the parsing of the previous block. Correspondingly, one block type is "ParsingFailedBlock".
 
 #### Middleware
-Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resoling crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, no not mutate their input, but return a modified copy.
+Middleware layers transform a library and its blocks, for example by decoding latex special characters, interpolating string references, resolving crossreferences or re-ordering blocks. Thus, the choice of middleware allows to customize parsing and writing to ones specific usecase. Note: Middlewares, by default, do not mutate their input, but return a modified copy.
 
 #### Writer
 Writes the content of a bibtex library to a ``.bib`` file. Optional formatting parameters can be passed using a corresponding dedicated data structure.

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ bibtexparser/entrypoint.py
 bibtexparser/exceptions.py
 bibtexparser/library.py
 bibtexparser/model.py
+bibtexparser/py.typed
 bibtexparser/splitter.py
 bibtexparser/writer.py
 bibtexparser.egg-info/PKG-INFO

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/bibtexparser.egg-info/requires.txt

@@ -1,4 +1,4 @@
-pylatexenc>=2.10
+pylatexenc~=2.10
 
 [docs]
 sphinx

{bibtexparser-2.0.0b8 → bibtexparser-2.0.0b9}/setup.py

@@ -29,16 +29,22 @@ setuptools.setup(
     description="Bibtex parser for python 3",
     long_description_content_type="text/markdown",
     long_description=load_readme(),
+    python_requires=">=3.9",
     packages=setuptools.find_packages(include=["bibtexparser", "bibtexparser.*"]),
+    package_data={"bibtexparser": ["py.typed"]},
     classifiers=[
         "Development Status :: 4 - Beta",
         "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
         "Topic :: Scientific/Engineering :: Artificial Intelligence",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
     install_requires=[
-        "pylatexenc>=2.10",
+        "pylatexenc~=2.10",
     ],
     extras_require={
         "test": [

bibtexparser-2.0.0b9/tests/test_entrypoint.py

@@ -0,0 +1,243 @@
+"""Testing the parse_file and write_file functions."""
+
+import os
+import tempfile
+import warnings
+
+import pytest
+
+from bibtexparser import parse_file
+from bibtexparser import write_file
+from bibtexparser import write_string
+from bibtexparser.library import Library
+from bibtexparser.model import Entry
+from bibtexparser.model import Field
+
+
+def test_gbk():
+    library = parse_file("tests/resources/gbk_test.bib", encoding="gbk")
+    assert library.entries[0]["author"] == "凯撒"
+    assert library.entries[0]["title"] == "Test Title"
+    assert library.entries[0]["year"] == "2013"
+    assert library.entries[0]["journal"] == "测试期刊"
+
+
+def test_write_file_default_encoding():
+    """Test write_file uses UTF-8 by default."""
+    entry = Entry(
+        entry_type="article",
+        key="test2024",
+        fields=[
+            Field(key="author", value="Müller"),
+            Field(key="title", value="Ångström measurements"),
+        ],
+    )
+    library = Library([entry])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        write_file(temp_path, library)
+        # Read back and verify
+        with open(temp_path, encoding="UTF-8") as f:
+            content = f.read()
+        assert "Müller" in content
+        assert "Ångström" in content
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_gbk_encoding():
+    """Test write_file with GBK encoding for Chinese characters."""
+    entry = Entry(
+        entry_type="article",
+        key="test2024",
+        fields=[
+            Field(key="author", value="凯撒"),
+            Field(key="title", value="Test Title"),
+            Field(key="journal", value="测试期刊"),
+        ],
+    )
+    library = Library([entry])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        write_file(temp_path, library, encoding="gbk")
+        # Read back with GBK and verify
+        with open(temp_path, encoding="gbk") as f:
+            content = f.read()
+        assert "凯撒" in content
+        assert "测试期刊" in content
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_roundtrip_gbk():
+    """Test round-trip: parse GBK file, write with GBK, parse again."""
+    # Parse original GBK file
+    library = parse_file("tests/resources/gbk_test.bib", encoding="gbk")
+    original_author = library.entries[0]["author"]
+    original_journal = library.entries[0]["journal"]
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        # Write with GBK encoding
+        write_file(temp_path, library, encoding="gbk")
+        # Parse back
+        library2 = parse_file(temp_path, encoding="gbk")
+        assert library2.entries[0]["author"] == original_author
+        assert library2.entries[0]["journal"] == original_journal
+    finally:
+        os.unlink(temp_path)
+
+
+# Deprecation warning tests for write_file and write_string
+def test_write_file_deprecated_parse_stack_parameter():
+    """Test that using deprecated 'parse_stack' parameter issues a warning."""
+    library = Library([])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            write_file(temp_path, library, parse_stack=[])
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "parse_stack" in str(w[0].message)
+            assert "unparse_stack" in str(w[0].message)
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_deprecated_append_middleware_parameter():
+    """Test that using deprecated 'append_middleware' parameter issues a warning."""
+    library = Library([])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            write_file(temp_path, library, append_middleware=[])
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "append_middleware" in str(w[0].message)
+            assert "prepend_middleware" in str(w[0].message)
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_both_parse_stack_and_unparse_stack_raises_error():
+    """Test that providing both parse_stack and unparse_stack raises ValueError."""
+    library = Library([])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        with pytest.raises(ValueError) as excinfo:
+            write_file(temp_path, library, parse_stack=[], unparse_stack=[])
+        assert "parse_stack" in str(excinfo.value)
+        assert "unparse_stack" in str(excinfo.value)
+        assert "Use 'unparse_stack' instead" in str(excinfo.value)
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_both_append_and_prepend_middleware_raises_error():
+    """Test that providing both append_middleware and prepend_middleware raises ValueError."""
+    library = Library([])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        with pytest.raises(ValueError) as excinfo:
+            write_file(temp_path, library, append_middleware=[], prepend_middleware=[])
+        assert "append_middleware" in str(excinfo.value)
+        assert "prepend_middleware" in str(excinfo.value)
+        assert "Use 'prepend_middleware' instead" in str(excinfo.value)
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_file_unexpected_keyword_argument_raises_error():
+    """Test that unexpected keyword arguments raise TypeError."""
+    library = Library([])
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bib", delete=False) as f:
+        temp_path = f.name
+
+    try:
+        with pytest.raises(TypeError) as excinfo:
+            write_file(temp_path, library, unknown_param="value")
+        assert "unexpected keyword arguments" in str(excinfo.value)
+        assert "unknown_param" in str(excinfo.value)
+    finally:
+        os.unlink(temp_path)
+
+
+def test_write_string_deprecated_parse_stack_parameter():
+    """Test that using deprecated 'parse_stack' parameter issues a warning."""
+    library = Library([])
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        write_string(library, parse_stack=[])
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "parse_stack" in str(w[0].message)
+        assert "unparse_stack" in str(w[0].message)
+
+
+def test_write_string_deprecated_append_middleware_parameter():
+    """Test that using deprecated 'append_middleware' parameter issues a warning."""
+    library = Library([])
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        write_string(library, append_middleware=[])
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "append_middleware" in str(w[0].message)
+        assert "prepend_middleware" in str(w[0].message)
+
+
+def test_write_string_both_parse_stack_and_unparse_stack_raises_error():
+    """Test that providing both parse_stack and unparse_stack raises ValueError."""
+    library = Library([])
+
+    with pytest.raises(ValueError) as excinfo:
+        write_string(library, parse_stack=[], unparse_stack=[])
+    assert "parse_stack" in str(excinfo.value)
+    assert "unparse_stack" in str(excinfo.value)
+    assert "Use 'unparse_stack' instead" in str(excinfo.value)
+
+
+def test_write_string_both_append_and_prepend_middleware_raises_error():
+    """Test that providing both append_middleware and prepend_middleware raises ValueError."""
+    library = Library([])
+
+    with pytest.raises(ValueError) as excinfo:
+        write_string(library, append_middleware=[], prepend_middleware=[])
+    assert "append_middleware" in str(excinfo.value)
+    assert "prepend_middleware" in str(excinfo.value)
+    assert "Use 'prepend_middleware' instead" in str(excinfo.value)
+
+
+def test_write_string_unexpected_keyword_argument_raises_error():
+    """Test that unexpected keyword arguments raise TypeError."""
+    library = Library([])
+
+    with pytest.raises(TypeError) as excinfo:
+        write_string(library, unknown_param="value")
+    assert "unexpected keyword arguments" in str(excinfo.value)
+    assert "unknown_param" in str(excinfo.value)

bibtexparser-2.0.0b8/tests/test_entrypoint.py

@@ -1,11 +0,0 @@
-"""Testing the parse_file function."""
-
-from bibtexparser import parse_file
-
-
-def test_gbk():
-    library = parse_file("tests/resources/gbk_test.bib", encoding="gbk")
-    assert library.entries[0]["author"] == "凯撒"
-    assert library.entries[0]["title"] == "Test Title"
-    assert library.entries[0]["year"] == "2013"
-    assert library.entries[0]["journal"] == "测试期刊"