Next steps; comments and questions

[hpjansson]

Hey! This is brilliant work. Sweet docs and everything. Here are a couple of quick comments and questions from me in no particular order:

API selection/warts

• What's your general impression of the API from a bindings perspective? I'm afraid parts of it aren't very binding-friendly -- did you come across anything you found particularly annoying?
• You may be able to get by without having bindings for everything. Especially the term sequence (ChafaTermInfo) methods may not be needed. They're mostly there to provide a fast API for the canvas and a couple of seqs for the chafa command-line utility (e.g. clear screen). But it's of course up to you. I'm working towards a terminal client class that will provide an abstraction over terminal control sequences and provide a session API for interactive applications and such, eventually.

Distribution and maintenance

• Do you envision this as being packaged in Linux/BSD distributions? @cdluminate is an expert Debian packager and Python programmer who may be able to help (probably pretty busy with research though!).
• I can give you a heads up before Chafa releases that add or change API so the bindings can be updated in time, if you want.
• I haven't broken any APIs since 1.0 (~2018), but there are some deprecations, and there will be a 2.0 release someday with an API cleanup. Don't yet know when that will be, in a year or two maybe?

Marketing stuff

• I'd like to link to your project from my Chafa pages, mention you in NEWS, etc. Also give you a shoutout on Mastodon and/or my blog. Is that ok? I'd link to https://chafapy.mage.black/ or wherever you prefer.
• Is it ok to use your full name? Any pronoun preferences?

Misc

• I'm open to any suggestions/comments on how to make your life easier or improve the project in general.

[GuardKenzie]

Hihi! Thanks for your kind words!

API selection/warts

I found API really nice to work with. Once I got over the hurdle of learning ctypes, everything was pretty easy going. Your documentation is really good and the only thing I needed to venture into the source for was the integer values of the enumerators.

The only thing that will (maybe) cause me trouble is all the terminal sequence emitters. I have yet to figure out how to implement those without resorting to typing each of them up manually. As you say, that part is not really necessary and will probably not be a priority for me at the moment. An abstract terminal client class would be pretty cool!

Distribution and maintenance

I hadn't really thought about other means of distribution except for PyPi and have little experience with those, however, I think it would be really useful since chafa could then be installed as a dependency (and many people do prefer to install python packages through their package manager). Any help with that would be greatly appreciated.

I would love a heads up on new features/changes! It shouldn't be too much work getting them implemented since the backbone is there now. You can always reach me through Discord or email (both of which are listed on my profile), whichever you prefer!

I avoided implementing methods listed as being deprecated in your documentation. I suspect when chafa 2.0 rolls around, I will also increase the major version of these bindings. People would then have a choice of installing the older 1.* bindings from PyPi if they so wish.

Marketing stuff

That would be amazing, yes please! Linking to chafapy.mage.black is fine. My full name is listed in the footer of the docs and my pronouns are she/her.

[hpjansson]

I've added links in a few places now, like the README, official web pages, etc. That should hopefully give a small search engine boost. I'll make sure to mention it when I announce the next major release too.

There's a new function on the master branch (slated for 1.14) with the signature gchar *chafa_term_info_emit_seq (ChafaTermInfo *term_info, ChafaTermSeq seq, ...). That lets you emit sequences by enum. However it's a varargs interface, and you still need to supply the correct number of arguments for each one. I could add a va_args or array-based entry point to the same functionality if you want to bind that. Then the "supply correct # of args" issue could be punted to the API user and you could return a runtime error if they get it wrong.

Packaging is something that'll happen gradually, I think. I'll ping a few more people when the annual January workload shock starts subsiding.

[GuardKenzie]

Thank you so much for adding a note about this little project to your stuff! I really appreciate it. ❤️

The chafa_term_info_emit_seq is going to come in really handy! I took a look at it and I think it should be pretty easy to bind as is. I'll take a better look at it when I get time.

About packaging, chafa.py now has binary releases available for every major system on PyPi so I think we're pretty good for now at least.

[GuardKenzie]

I have been playing around with chafa_term_info_emit_seq and it is really pretty perfect for binding as is! At the moment I check

1. if the terminal even supports the sequence with chafa_term_info_have_seq and raise a ValueError if it does not with "your terminal does not seem to support {sequence}".
2. if the terminal has the sequence and we get NULL back, I raise a TypeError with "incorrect number of args passed".

edit

This is super cool! I'm having wayyy too much fun with this hahaha

💽 Source

from chafa import *
from time import sleep
import sys

SL=15

def snake(n, step):
  if step < 0: turns = ["┏","┛"]
  else:        turns = ["┓", "┗"]

  if n == 1:
      return turns[0]
  elif n == SL - 1:
      return turns[1]

  return "┃"

def gradient(x, y):
  return (80 + 5*x, 255 - (100 + 10*y), 200)

# Grab our info
db = TermDb()
info = db.detect()

# Clear the terminal
clear     = info.emit(TermSeq.CHAFA_TERM_SEQ_CLEAR)
no_cursor = info.emit(TermSeq.CHAFA_TERM_SEQ_DISABLE_CURSOR)

print(clear.decode())
print(no_cursor.decode())

rows = list(range(1,SL))
cols = list(range(1,32))

for x in cols:
  # We want to step backwards if column is even
  step = 2 * (x%2) - 1

  for y in rows[::step]:
      # Grab char
      char = snake(y, step)

      # Move to position
      out = info.emit(
          TermSeq.CHAFA_TERM_SEQ_CURSOR_TO_POS, 
          x, y
      )

      # Set color
      color = info.emit(
          TermSeq.CHAFA_TERM_SEQ_SET_COLOR_FG_DIRECT,
          *gradient(x,y)
      )

      sys.stdout.buffer.write(out)
      sys.stdout.buffer.write(color)
      sys.stdout.write(char)
      sys.stdout.flush()

      sleep(0.01)

# All back to normal!
reset = info.emit(TermSeq.CHAFA_TERM_SEQ_RESET_TERMINAL_HARD)
print(reset.decode())

[hpjansson]

That sounds perfect. Love the procrastination application!