search

WhyNotHugo / python-barcode

㊙️ Create standard barcodes with Python. No external dependencies. 100% Organic Python.
http://python-barcode.rtfd.io/
MIT License
572 stars 123 forks source link

Why does `Barcode.build()` always return a singleton list? #228

Open maresb opened 6 months ago

maresb commented 6 months ago

The return type of Barcode.build() is List[str]. But in all overrides of .build(), the return value is always a singleton. I'm trying to understand the source code, and I find this really confusing, so I was wondering if there's an explanation. Is it for historical / backwards compatibility reasons?

I would have expected the return type to be str, so then I want to understand what lists of different lengths are supposed to mean. Maybe it would be good to at least include an explanatory comment to reduce confusion? Thanks!

WhyNotHugo commented 6 months ago

Is it for historical / backwards compatibility reasons?

This is almost always the answer for anything unclear in this codebase. It is a fork of an older, unmaintained, library from over a decade ago, and it's been hard to clean up these quirks without breaking backwards compatible.

At this point, I'm okay with making breaking API changes as long as they're clear and well documented. New versions follow semver to indicate breaking changes.

The return type of Barcode.build() is List[str]. But in all overrides of .build(), the return value is always a singleton.

True, I've confirmed that they all return a list with a single string. We can definitely change this to simply return a string instead.

maresb commented 6 months ago

Thanks a lot for the clear explanation. I feel for you on the quirky legacy codebase. All that callback nonsense is totally out of control. It'd be great to eventually have a clean functional interface, but I can see that it's a ton of work.