Skip to content

bib.bibtexparser.middlewares.middleware

Classes

BlockMiddleware 

BlockMiddleware(
    allow_parallel_execution=True,
    allow_inplace_modification=True,
)

Bases: Middleware, ABC

Transform a library on a per-block basis.

The BlockMiddleware replaces a block with zero, one or more new (transformed) blocks.

Changes may rely on the state of the overall library, but must not change the state of the library directly, except if allow_inplace_modification is true.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
19
20
21
22
23
24
25
26
def __init__(self, allow_parallel_execution: bool = True, allow_inplace_modification: bool = True):
    """Create a new Middleware.

    :param allow_inplace_modification: See corresponding property.
    :param allow_parallel_execution: See corresponding property.
    """
    self._allow_inplace_modification = allow_inplace_modification
    self._allow_parallel_execution = allow_parallel_execution

Functions

metadata_key classmethod 
metadata_key()

Tt is the identifier of the middleware.

This key is used to identify the middleware in a blocks metadata.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
59
60
61
62
63
64
65
@classmethod
def metadata_key(cls) -> str:
    """Tt is the identifier of the middleware.

    This key is used to identify the middleware in a blocks metadata.
    """
    return cls.__name__
transform_block 
transform_block(block, library)

Transform a block.

:param block: Block to transform. :param library: Library containing the block. Should typically not be modified during the transformation, but be considered as read-only. If the library is modified, make sure to set the allow_multithreading constructor argument to false :return: Transformed block. If the block should be removed, return None. If the block should be replaced by multiple blocks, return a collection of blocks. If the block should be replaced by a single block, return the single block. If the block should not be modified, return a copy of the original block. The returned block has to be a new instance, except if self.allow_inplace_modification is True (in which case the block may also return the original block).

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def transform_block(self, block: Block, library: Library) -> Block | Collection[Block] | None:
    """Transform a block.

    :param block: Block to transform.
    :param library: Library containing the block.
        Should typically not be modified during
        the transformation, but be considered as read-only.
        If the library is modified, make sure to set the `allow_multithreading`
        constructor argument to false
    :return: Transformed block. If the block should be removed, return None.
        If the block should be replaced by multiple blocks, return a collection
        of blocks. If the block should be replaced by a single block, return
        the single block. If the block should not be modified, return a copy of
        the original block.
        The returned block has to be a new instance, except if
        `self.allow_inplace_modification` is True (in which case the block
        may also return the original block).
    """
    block = block if self.allow_inplace_modification else deepcopy(block)
    if isinstance(block, Entry):
        return self.transform_entry(block, library)
    elif isinstance(block, String):
        return self.transform_string(block, library)
    elif isinstance(block, Preamble):
        return self.transform_preamble(block, library)
    elif isinstance(block, ExplicitComment):
        return self.transform_explicit_comment(block, library)
    elif isinstance(block, ImplicitComment):
        return self.transform_implicit_comment(block, library)

    # logger.warning(f"Unknown block type {type(block)}")
    return block
transform_entry 
transform_entry(entry, library)

Transform an entry. Called by transform_block if the block is an entry.

Note: This method modifies the passed entry. For a method respecting the allow_inplace_modification property, you should use transform or transform_block instead.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
127
128
129
130
131
132
133
134
def transform_entry(self, entry: Entry, library: Library) -> Block | Collection[Block] | None:
    """Transform an entry. Called by `transform_block` if the block is an entry.

    Note: This method modifies the passed entry. For a method
    respecting the `allow_inplace_modification` property,
    you should use `transform` or `transform_block` instead.
    """
    return entry
transform_explicit_comment 
transform_explicit_comment(explicit_comment, library)

Transform an explicit comment. Called by transform_block if the block is an explicit comment.

Note: This method modifies the passed explicit comment. For a method respecting the allow_inplace_modification property, you should use transform or transform_block instead.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
154
155
156
157
158
159
160
161
162
163
def transform_explicit_comment(
    self, explicit_comment: ExplicitComment, library: Library
) -> Block | Collection[Block] | None:
    """Transform an explicit comment. Called by `transform_block` if the block is an explicit comment.

    Note: This method modifies the passed explicit comment. For a method
    respecting the `allow_inplace_modification` property,
    you should use `transform` or `transform_block` instead.
    """
    return explicit_comment
transform_implicit_comment 
transform_implicit_comment(implicit_comment, library)

Transform an implicit comment. Called by transform_block if the block is an implicit comment.

Note: This method modifies the passed implicit comment. For a method respecting the allow_inplace_modification property, you should use transform or transform_block instead.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
165
166
167
168
169
170
171
172
173
174
def transform_implicit_comment(
    self, implicit_comment: ImplicitComment, library: Library
) -> Block | Collection[Block] | None:
    """Transform an implicit comment. Called by `transform_block` if the block is an implicit comment.

    Note: This method modifies the passed implicit comment. For a method
    respecting the `allow_inplace_modification` property,
    you should use `transform` or `transform_block` instead.
    """
    return implicit_comment
transform_preamble 
transform_preamble(preamble, library)

Transform a preamble. Called by transform_block if the block is a preamble.

Note: This method modifies the passed preamble. For a method respecting the allow_inplace_modification property, you should use transform or transform_block instead.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
145
146
147
148
149
150
151
152
def transform_preamble(self, preamble: Preamble, library: Library) -> Block | Collection[Block] | None:
    """Transform a preamble. Called by `transform_block` if the block is a preamble.

    Note: This method modifies the passed preamble. For a method
    respecting the `allow_inplace_modification` property,
    you should use `transform` or `transform_block` instead.
    """
    return preamble
transform_string 
transform_string(string, library)

Transform a string. Called by transform_block if the block is a string.

Note: This method modifies the passed string. For a method respecting the allow_inplace_modification property, you should use transform or transform_block instead.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
136
137
138
139
140
141
142
143
def transform_string(self, string: String, library: Library) -> Block | Collection[Block] | None:
    """Transform a string. Called by `transform_block` if the block is a string.

    Note: This method modifies the passed string. For a method
    respecting the `allow_inplace_modification` property,
    you should use `transform` or `transform_block` instead.
    """
    return string

LibraryMiddleware 

LibraryMiddleware(allow_inplace_modification=True)

Bases: Middleware, ABC

Changes an overall library at once (not just on a per-block basis).

Examples of library-wide changes are: - Re-Sorting the blocks in the library. - Transforming the library instance to a custom subclass of Library.

Whatever can be done in a BlockMiddleware, should be done in a BlockMiddleware (and not in a LibraryMiddleware), for performance reasons (e.g. deleting blocks, ...).

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
189
190
191
192
def __init__(self, allow_inplace_modification: bool = True):
    # As library middleware is run per library (not per block individually),
    #   it cannot be parallelized.
    super().__init__(allow_inplace_modification=allow_inplace_modification, allow_parallel_execution=False)

Functions

transform 
transform(library)

Transform a library.

:param library: Library to transform. :return: Transformed library. If the library should not be modified, return a copy of the original library. The returned library has to be a new instance, except if self.allow_inplace_modification is True (in which case the library may also return the original library).

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
194
195
196
197
198
199
200
201
202
203
204
205
def transform(self, library: Library) -> Library:
    """Transform a library.

    :param library: Library to transform.
    :return: Transformed library. If the library should not be modified,
        return a copy of the original library.
        The returned library has to be a new instance, except if
        `self.allow_inplace_modification` is True (in which case the library
        may also return the original library).
    """
    library = library if self.allow_inplace_modification else deepcopy(library)
    return library

Middleware 

Middleware(
    allow_parallel_execution=True,
    allow_inplace_modification=True,
)

Bases: ABC

Implements a function to transform a block or library.

Abstract Class. You should extend either BlockMiddleware or LibraryMiddleware

Create a new Middleware.

:param allow_inplace_modification: See corresponding property. :param allow_parallel_execution: See corresponding property.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
19
20
21
22
23
24
25
26
def __init__(self, allow_parallel_execution: bool = True, allow_inplace_modification: bool = True):
    """Create a new Middleware.

    :param allow_inplace_modification: See corresponding property.
    :param allow_parallel_execution: See corresponding property.
    """
    self._allow_inplace_modification = allow_inplace_modification
    self._allow_parallel_execution = allow_parallel_execution

Attributes

allow_inplace_modification property 
allow_inplace_modification

If true, the middleware may modify the block in-place.

I.e., if true, the output of transform may be the same instance as the input. If false, new instances must be returned.

allow_parallel_execution property 
allow_parallel_execution

True indicates that the middleware is threadsafe.

Functions

transform abstractmethod 
transform(library)

Apply transformation to a library. Main entrypoint of the middleware.

Source code in pybibtexer/bib/bibtexparser/middlewares/middleware.py 
42
43
44
45
@abc.abstractmethod
def transform(self, library: Library) -> Library:
    """Apply transformation to a library. Main entrypoint of the middleware."""
    raise NotImplementedError("called abstract method")