✨ Allow simple way to create custom block sorting

[MiWeiss]

We'd want to facilitate users sorting blocks according to their needs.

They easiest and most general way to do this would probably be to create a new abstract class SortBlocksMiddleware with the following properties:

• The abstract class should have just one unimplemented method, and it should have the signature compare(block1, block2) -> int, following the standard convention that any returned value > 0 indicates that block2 should come anywhere after block1, any value <0 the opposit and a return value of 0 sais that any order of the two should be fine.
• The docstring of the compare method should list the standard conventions for such a method (the conditions above, but also that it's transitive, pure, ...)
• Our own SortBlocksByTypeAndKeyMiddleware should extend/implement SortBlocksMiddleware
• The documentation should provide a simple MWE

Location of the code: https://github.com/sciunto-org/python-bibtexparser/blob/main/bibtexparser/middlewares/sorting_blocks.py

I am currently not working on this, so feel free to comment below if you want to take over.

[mirhahn]

Hi,

I would like to take a crack at this. I have a code at work that renders BibTeX into HTML and I ran into the issue of having to code custom sorting for the bibtexparser-v2 port as well (I sort by keys made up of multiple fields, including author names and release dates, that are supposed to be specified by the user).

I have a few questions:

1. Do you have style guidelines aside from those mentioned in this Issue and in CONTRIBUTING.md? Do you have a preferred docstring format?
2. How exactly do the allow_inplace_modification and allow_parallel_execution flags work? Especially for the latter, what do I need to do to accommodate that functionality?
3. What is your targeted minimal Python version? It's not specified in setup.py as far as I can see and I like heavily annotating my code with type hints, which can easily slip in dependencies on newer standard libraries if I don't know what to target. I assume everything post-3.8 is okay, right?
4. Do you know of a good way to generate random BibTeX files for testing?

It might take me a bit. Day job takes precedence.

Edit: Regarding the docstrings, I see some Sphinx-autodoc stuff here and there, but not everywhere.

[MiWeiss]

Hi @mirhahn

Awesome, thanks a lot!

Do you have style guidelines aside from those mentioned in this Issue and in CONTRIBUTING.md? Do you have a preferred docstring format?

No. Go ahead. I personally like google docstyle the best and think it's used most frequently in the repo, but so far we're not enforcing it. Should probably do that eventually, though ;-)

How exactly do the allow_inplace_modification and allow_parallel_execution flags work? Especially for the latter, what do I need to do to accommodate that functionality?

Well, if your implementation is capable of parallel execution (has no race condition, is threadsafe, ...) just pass "true" to the superclass. Otherwise, pass "false". Note however thata at the moment, parallel execution is not yet supported, thus this is more something to be prepared once this is eventually implemented in the parser.

What is your targeted minimal Python version? It's not specified in setup.py as far as I can see and I like heavily annotating my code with type hints, which can easily slip in dependencies on newer standard libraries if I don't know what to target. I assume everything post-3.8 is okay, right?

Any version which is not yet EOL. Thus, I assume we'll drop 3.8 support later this year.

Do you know of a good way to generate random BibTeX files for testing?

Search for .bib files on github or google. This gives you real data, which is better than random ;-) Otherwise, use your favorite LLM (e.g. ChatGPT) , which are pretty good at generating reasonable test data, although in my experience often lack corner cases and diversity.