API Design - Request for feedback

[madsmtm]

Hi everyone, I've been working on v2 for a while now, and it's getting close to a point where I can start making alpha releases!

However, reworking this has been a mostly one-man effort, and I'd really like some input on how these changes are going to suit everyone else (after all, you're probably using this library more than I am 😁). Additionally, if you need me to elaborate on something, or explain the reasoning behind these API choices, I'd be more than happy to!

You can also use this issue as a way of requesting features, if there's something, important or not, we're missing!

A quick primer of major changes before we begin:

• No Python 2 support
• Type hints
• Better listening system (no more error-prone subclassing)
• Cleaner way of interracting with threads
  • client.changeThreadColor(color, thread_id=thread_id) -> thread.set_color(color)
• async/await, backed by asyncio - Not yet implemented, follow asyncio fbchat #411 for more

Interracting with threads

Digging a bit further into the details, I'd like input on the changed API when interracting with threads. Previously, you'd call a method in Client with a thread ID and a ThreadType. This was pretty error prone, and involved a lot of extra typing. Now you simply create a Group/User object (or more often, fetch it from somewhere), and call methods on that.

An example:

# Old
import fbchat
client = fbchat.Client("<email>", "<password>")
print("Own id: {}".format(client.uid))

client.send(fbchat.Message(text="Hi me!"), thread_id=client.uid, thread_type=fbchat.ThreadType.USER)

client.send(fbchat.Message(text="Hi group!"), thread_id="<group id>", thread_type=fbchat.ThreadType.GROUP)

# New
import fbchat
session = fbchat.Session.login("<email>", "<password>")
print("Own id: {}".format(session.user.id))

session.user.send_text("Hi me!")

group = fbchat.Group(session=session, id="<group id>")
group.send_text("Hi group!")

Note also how we have pretty clear separation of concerns (Session handles logging in, Group handles interracting with the group).

Listening

Regarding listening, you'd previously override Client, and provide a custom implementation of an onX method. This was pretty error prone, and made it difficult for me to add new features. Now you create a Listener object, and register methods based on type hints.
How this is going to work exactly is very much up for discussion, so please comment on this!

An example:

# Old
import fbchat

class CustomClient(fbchat.Client):
    def onMessage(self, author_id, message, thread_id, thread_type, **kwargs):
        # If you're not the author, echo
        if author_id != self.uid:
            self.send(fbchat.Message(text=message), thread_id=thread_id, thread_type=thread_type)

client = CustomClient("<email>", "<password>")
client.listen()

# New
import fbchat
session = fbchat.Session.login("<email>", "<password>")
listener = fbchat.Listener(session=session, ...)  # TODO: Addition parameters

@listener.register
def on_message(event: fbchat.MessageEvent):
    # If you're not the author, echo
    if event.author.id != session.user.id:
        event.thread.send_text(event.message.text)

listener.run()

A few notes before we round this off:

• I probably won't be adding caching, the requirements for this changes vastly across applications, so I'd rather provide a solid foundation that people can build this upon
• See Version 2 wishlist #396 for the wishlist, and feature requests
• If you want to see more examples of how the API has changed, you can look at the difference between the v1 examples and the current WIP examples

Thanks for your time 👍

[syspic]

Oops sorry for getting to this so late. I do have some input

Interacting with threads looks a lot better now! But I still have one concern. Since all of this is done by ID and I don't want to send too many requests and get banned (I've gotten temporarily suspended more than I would like). My solution to this is making two dictionaries that maps a persons/group name to their/its id and backwards. So I can do something like this

name = idToName.get("10000")
id = nameToId.get("person")

Now you definitely have to make an object per group/person you're interacting with. Originally I could just do if not this id, skip the on_message or for every message I get in on_message, do this/send this. But now it seems like I would have to make a new group/user object in order to interact with it?

The listening seems pretty intuitive which is great! My guess is for the onX methods, youd just do more of

@listener.register
def on_X():

Is that right? If we have to do that, what is the default use? Originally, you could see what the Client's method was and then override it. Mostly it was just printing stuff out

Lastly, how difficult would it be to change from the v1 to the new v2? I assume that installing will be as easy as a pip install but the code would need a refactoring? I know this is a ways out though. Ive lost a few projects due to unfortunate events so I have to redo them . But I don't want to get too deep into a v1 project if I can wait for v2

[TheLastGimbus]

But now it seems like I would have to make a new group/user object in order to interact with it?
and I don't want to send too many requests and get banned

This is important. Is User/Group already in fbchat.MessageEvent ?

[madsmtm]

I'll try to answer as best as I can, @syspic, but I may not have understood everything fully, so please elaborate if my answer doesn't make sense 😉.

My solution to this is making two dictionaries that maps a persons/group name to their/its id and backwards

A problem with nameToId is that you need to store the type of the thread as well - but that may not have been relevant in your use case.

Originally I could just do if not this id, skip the on_message or for every message I get in on_message, do this/send this

Like @TheLastGimbus noted, the fbchat.MessageEvent object you would be receiving would have a .thread attribute, that you could use, e.g. look up using event.thread.id.

youd just do more of

@listener.register
def on_X():

I haven't really thought this through entirely, but I think I wanted it to work with type hints. So the function name is irrelevant. The following two functions would both listen to the fbchat.MessageEvent, and would be called in an arbitary order:

@listener.register
def do_echo(event: fbchat.MessageEvent):
    # If you're not the author, echo
    if event.author.id != session.user.id:
        event.thread.send_text(event.message.text)

@listener.register
def kick_people(event: fbchat.MessageEvent):
    if event.message.text == 'Kick me!':
        event.thread.remove_participant(event.author)

Alternatively, if this seems a little magical, we could just take a parameter to the .register function:

@listener.register(fbchat.MessageEvent)
def do_echo(event):
    # If you're not the author, echo
    if event.author.id != session.user.id:
        event.thread.send_text(event.message.text)

how difficult would it be to change from the v1 to the new v2

Probably very. The API surface was almost entirely on the Client model, now it's split across several models.

Hope that answers your concerns, thanks for the questions!

[madsmtm]

To @TheLastGimbus, if you know the ID, creating a new User or Group object will always be "free", in the sense that it won't send a request to Facebook - And hence, you can't get banned for it 😉

[TheLastGimbus]

Okay, so how do I know User.name by just passing it ID? How does it know? Does Group contain something like Group.members?

[madsmtm]

A little explanation:
There's User/Group, which you can create yourself and interract with:

user = fbchat.User(session=session, id="123")  # Does not call facebook, therefore doesn't contain further data
user.send_text('abc')
user.name  # Raises an error

And then there's UserData/GroupData (which inherits User/Group), which you receive from various functions, on which you can get the name, and interract with:

users = list(client.search_for_users('Abc', limit=1))  # Calls facebook, and recieves relevant data
print(users[0].name)
users[0].send_text('abc')

So when listening for messages, you would get a MessageEvent with a User object as it's thread. So you would have to make a dictionary yourself somewhere, that maps a user id to a name, e.g.:

id_to_name = {}
@listener.register(fbchat.MessageEvent)
def do_echo(event):
    if event.author.id not in id_to_name:
        # Fetch name, and cache for future usage
        author, = client.fetch_thread_info([event.author.id])
        id_to_name[author.id] = author.name
    if event.author.id != session.user.id:
        event.thread.send_text(f"Hello there {id_to_name[event.author.id]}")

[madsmtm]

I hope this makes sense, if you have ideas on how to improve this design, or if it seems confusing, let me know! 🙂

[MariposaLand]

Thank you for your work on Fbchat.  I used it once but it received an error due to fact the my message was in the MARKETPLACE folder. Have you or are you planning on supporting this addition object?  Additionally, have you looked at using BERT in text analytics within FB messages? Many thanks Tim Zimmerman  Sent from Yahoo Mail for iPhone On Wednesday, February 5, 2020, 8:19 AM, Mads Marquart <notifications@github.com> wrote: Hi everyone, I've been working on v2 for a while now, and it's getting close to a point where I can start making alpha releases! However, reworking this has been a mostly one-man effort, and I'd really like some input on how these changes are going to suit everyone else (after all, you're probably using this library more than I am 😁 ). Additionally, if you need me to elaborate on something, or explain the reasoning behind these API choices, I'd be more than happy to! You can also use this issue as a way of requesting features, if there's something, important or not, we're missing! A quick primer of major changes before we begin: - No Python 2 support - Type hints - Better listening system (no more error-prone subclassing) - Cleaner way of interracting with threads - client.changeThreadColor(color, thread_id=thread_id) -> thread.set_color(color) - async/await, backed by asyncio - Not yet implemented, follow #411 for more Interracting with threads Digging a bit further into the details, I'd like input on the changed API when interracting with threads. Previously, you'd call a method in Client with a thread ID and a ThreadType. This was pretty error prone, and involved a lot of extra typing. Now you simply create a Group/User object (or more often, fetch it from somewhere), and call methods on that. An example: # Old import fbchat client = fbchat.Client("<email>", "<password>") print("Own id: {}".format(client.uid)) client.send(fbchat.Message(text="Hi me!"), thread_id=client.uid, thread_type=fbchat.ThreadType.USER) client.send(fbchat.Message(text="Hi group!"), thread_id="<group id>", thread_type=fbchat.ThreadType.GROUP) # New import fbchat session = fbchat.Session.login("<email>", "<password>") print("Own id: {}".format(session.user.id)) session.user.send_text("Hi me!") group = fbchat.Group(session=session, id="<group id>") group.send_text("Hi group!") Note also how we have pretty clear separation of concerns (Session handles logging in, Group handles interracting with the group). Listening Regarding listening, you'd previously override Client, and provide a custom implementation of an onX method. This was pretty error prone, and made it difficult for me to add new features. Now you create a Listener object, and register methods based on type hints. How this is going to work exactly is very much up for discussion, so please comment on this! An example: # Old import fbchat class CustomClient(fbchat.Client): def onMessage(self, author_id, message, thread_id, thread_type, **kwargs): # If you're not the author, echo if author_id != self.uid: self.send(fbchat.Message(text=message), thread_id=thread_id, thread_type=thread_type) client = CustomClient("<email>", "<password>") client.listen() # New import fbchat session = fbchat.Session.login("<email>", "<password>") listener = fbchat.Listener(session=session, ...) # TODO: Addition parameters @listener.register def on_message(event: fbchat.MessageEvent): # If you're not the author, echo if event.author.id != session.user.id: event.thread.send_text(event.message.text) listener.run() A few notes before we round this off: - I probably won't be adding caching, the requirements for this changes vastly across applications, so I'd rather provide a solid foundation that people can build this upon - See #396 for the wishlist, and feature requests Thanks for your time 👍 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[madsmtm]

Hmm, I don't know what BERT is? But yeah, I do want to support the MARKETPLACE stuff, I just haven't had access to it myself, so I haven't seen the errors everyone else are getting 🙄

[MariposaLand]

Thank you for the response. I will have to go to the office to see if I can recreate the error. You might just go to marketplace and post something for sale and have some friends of yours send you some messages for your test data.  Here is the info on BERT. https://www.searchenginejournal.com/bert-explained-what-you-need-to-know-about-googles-new-algorithm/337247/  Regards  Tim Zimmerman  Sent from Yahoo Mail for iPhone On Friday, March 6, 2020, 9:57 AM, Mads Marquart <notifications@github.com> wrote: Hmm, I don't know what BERT is? But yeah, I do want to support the MARKETPLACE stuff, I just haven't had access to it myself, so I haven't seen the errors everyone else are getting 🙄 — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[MariposaLand]

Here is an example of BERT in a chatbot https://pypi.org/project/Bert-Chatbot/#data  Sent from Yahoo Mail for iPhone On Friday, March 6, 2020, 9:57 AM, Mads Marquart <notifications@github.com> wrote: Hmm, I don't know what BERT is? But yeah, I do want to support the MARKETPLACE stuff, I just haven't had access to it myself, so I haven't seen the errors everyone else are getting 🙄 — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[madsmtm]

A quick notification, I've released an alpha version v2.0.0a1. The listening system is a bit different from what I wrote above, I wasn't entirely happy with it, so I ripped it out for now.

But now you have something to play with, then we can better start talking how it should work in detail!