miscellaneous considerations

[faretek1]

looking at scapi

Note

I will probably not catch everything. I am just gleaning, and I'm not 100% digging into their code

Miscellaneous considerations which I glean from comparing scapi with scratchattach. considerations which I think would be worth implementing at some point:

• datetime.fromisoformat using tz_info with UTC for datetimes. Not everyone is on UTC! (japan is 9hrs off so ig thats why they noticed)
• scapi uses a lot of dynamic importing stuff, even using global vars. While session.Session is a little verbose, ...I think it's better than importing into every function among other things
• scapi distinguishes different sources of activity - studios, users, messages, the feed, and classrooms
• scapi uses an UNKNOWN singleton value (which is an enum value), and has its own generic type MAYBE_UNKNOWN to go with it. in scratchattach we just use None and Optional. not sure if this is worth implementing
• scapi does not use self.__dict__.update but does use setattr i think
• for classrooms, scapi uses a ubiquitous edit method instead of individual setters for the title/description etc, which reflects the actual HTTP API better - and is more network-efficient
• scapi allows for bulk student account creation using csv. it converts a dict[str,str] into a csv string
• scapi's student account creation methods return Session objects, which is interesting, but any initialization cost must be considered. If every initialization incurred a network request, this would be a bad idea.
• scapi seems to handle a bunch of logic to do with getting a class token etc, which is interesting. maybe investigate
• i do not think scapi supports ended classes properly?
• scapi uses yield instead of using lists. this is a really good idea for efficiency. Maybe it is less user friendly but you can just use list(generator)
• scapi has report and some other dubious functionality. Not sure timmccool wants this in scratchattach
• scapi has proper support for ocular reactions rather than just returning a dict
• i personally have not really been testing scratchattach.site.forum. this means that there may well be regressions there and development should be made there. Scapi is likely better for that use case but I am unsure
• scapi makes extensive use of datetime and has manual conversions from the strings that scratch gives to real dates! this is much better than scratchattach in that regard. I previously considered using dateparser however that is a pretty large dependency. spending the time to write manual parsers is commendable and something we should definitely do. we should also standardize the variable names for dates. I suggest the suffix _at: e.g. created_at, modified_at, shared_at, or the prefix: dt_created, dt_modified, dt_shared
• scapi has native support for scratch news instead of just returning a json object
• scapi uses an enum for checking username/email validity instead of just returning whatever scratch sent:

if msg in PasswordStatus:
    return PasswordStatus(data.get("msg"))
else:
    return UNKNOWN

• scapi does not provide enums for the tts/translation services. I think the one we have is a little over complicated though
• scapi has a lot of dataclasses flying around because it provides typing for every function output in this way. more user friendly than typeddicts, and much better than just returning arbitrary json data
• regardless of scapi - remixtree was dropped by scratch so we should remove the functionality
• scapi uses @property for value access that does not require a web request
• scapi has CommentEvent which monitors replies (i think) - but we should note that there is a reply limit of 25 (i think)
• scapi has project report capabilities and some documentation for it. not sure we want that as that would facilitate mass reporting
• scapi differentiates the main home page mainpage.py with the other apis
• scapi's logout implementation is different to scratchattach and may actually work??
• scapi does support changing password etc. timmccool does not want this, as i linked above
• scapi allows you to change your email subscription. idk why u need this
• scapi has some stuff for promoting to scratcher etc. it possibly supports more API endpoints than scratchattach. we should review that
• scapi supports password reset email sending. i implemented this once on my own machine because i was handling 100+ accounts (most are deleted now, thankfully)
• scapi's docstrings seem to have more coverage than ours
• educator_can_unban is worth investigating?
• scapi has html_iterative. while this is interesting I do not think it would be very reliable - e.g. if you are watching griffpatch comments, you could get duplicates because it is so active
• scapi has a student password reset method
• scapi has a whole file for activity types - idk if that is necessary
• scapi has a http wrapper but does not seem to check the json validity like scratchattach does
• scapi seems to support a proxy or something. hmm....
• scapi types kwargs using typing.Unpack and typeddict
• scapi.CommentError.feedback might be worth investigating
• regardless of scapi - the root __init__.py file should really have an __all__ attribute that lists all of the imported names. this is tedious and annoying but necessary for type checkers like pyright to work properly