My thoughts:

I'm not a fan of a set(type=TextType.Bold)-style API. That's a Java-ism to me. There isn't any benefit in Python compared to a string: set(type="bold"). Only now I have to import extra types (and google the naming of TextType).
I do like staying close to raw ESC/POS. The text_type argument we currently have is our own invention, I don't see the need for that. Just let the user set "bold" and "underline" separately.
I like simplicity. Boldness is a boolean, so I would suggest set_bold(True). If the term used were "weight", I would still prefer set_weight("bold"). For underline, which has single and double options, I would support: set_underline(True|False|single|double).
I like separating set() into distinct methods. I should be able to set the boldness without affecting the font.
I also like to have a generic set()method, because it can be used with kwargs. But I've been wondering if that set() should have any defaults, or if it only should write those commands that the user requested.

I get why set() tries to reset all other properties to defaults. But it's not clear why for example the line spacing would not be reset. I.e. what belongs inside set() and what doesn't? It might also be confusing. When I first started, I knew that an empty set() call is some kind of "reset", but I didn't know it's just python-escpos own idea of a reset.

Basically, this is about whether we want our API to just map to a raw ESC/POS command, or whether we want the API to have aspects of a layout engine that executes ESC/POS commands for you.

The second thing is certainly useful. I wonder if that, we could come up with something different entirely. Just some spontaneous ideas:
- Like MagicEncode, we keeps track of state. If I call magic_set(bold=True) and then magic_set(), the only command executed the second time is turning of bold.
- Even without tracking state, we could do:

         engine = LayoutEngine(printer_driver, defaults={bold: True, width=4, font=a}}); 

         # set everything to the default, except weight
         engine.set(weight=2)  

         # change the defaults for this block
         with engine.block(vertical_spacing=2) as block:  
             block.set(bold=True)
             block.text("this text is bold")
             block.set(underline=True)
             block.text("this text is underlined but not bold")

         # another API idea
         engine.text("this text is bold", bold=True)  
         engine.text("this text is underlined but not bold", underline=True)

This way we have both; a low-level API where I can send ESC/POS commands without any magic (but with nice names), and an API that makes it easier to assemble the style changes I want to make for every line.

The high-level API may also provide things such as hr() to output a line that matches the column width. I'm also working on https://github.com/miracle2k/py-xml-escpos as an even higher-level construct, but some of the logic (like aligning text both left and right in the same line) are not just useful via XML; they could also be useful in code, e.g, say:

layout_engine.line(left="foo", right="foo")
layout_engine.columns("left", "center", "right")

ideas for api changes #176

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions