Friendly methods

[Lonami]

Use of raw API should be the exception, not the norm. Our client should offer an idiomatic interface for the most commonly used methods.

Starting by porting Telethon's client methods would be a good start (not including all, and not necessarily with the same name).

Methods which are in my opinion worth implementing (as of Telethon 1.21.1, on the left Telethon's naming, on the right implemented versions):

• Auth
  • [x] send_code_request. request_login_code.
  • [x] sign_in. sign_in and bot_sign_in
  • [x] sign_up. sign_up.
  • [x] log_out. sign_out.
  • [ ] edit_2fa. Not yet implemented.
• Base
  • [x] connect. connect.
  • [ ] disconnect. Not yet implemented. Dropping all the clients will close the connection, but should there be a way to disconnect the client so that the rest start failing with "not connected"?
• Messages
  • [x] send_message. send_message.
  • [x] edit_message. edit_message.
  • [x] delete_messages. delete_messages.
  • [x] forward_messages. forward_messages.
  • [x] iter_messages. iter_messages, search_messages and search_all_messages.
  • [x] pin_message. pin_message.
  • [x] unpin_message. unpin_message.
  • [x] send_read_acknowledge. mark_as_read.
• Uploads
  • [x] send_file. send_message already serves its purpose.
  • [x] upload_file. upload_file and upload_stream.
• Downloads
  • [x] download_media. download_media.
  • [ ] download_profile_photo. Not yet implemented. Probably should be covered by download_media instead though, rather than being its own method.
  • [x] iter_download. iter_download.
• Dialogs
  • [x] iter_dialogs. iter_dialogs.
  • [ ] edit_folder. Not yet implemented. We may want to deviate from what Telethon is currently doing here though, and provide something nicer.
  • [ ] iter_drafts. Not yet implemented.
  • [x] delete_dialog. delete_dialog.
• Users
  • [x] get_me. get_me.
  • [x] is_bot. Not yet implemented. Note that this should belong to the session, not the client.
  • [x] is_user_authorized. is_authorized.
  • [x] get_entity. resolve_username and unpack_chat.
• Chats
  • [x] iter_participants. iter_participants.
  • [x] kick_participant. kick_participant.
  • [ ] iter_admin_log. Not yet implemented.
  • [x] iter_profile_photos. iter_profile_photos.
  • [x] edit_admin. set_admin_rights.
  • [x] edit_permissions. set_banned_rights.
  • [ ] get_permissions. Not yet implemented.
  • [ ] get_stats. Not yet implemented.
  • [ ] action. Not yet implemented. We will need to review how this should be implemented in grammers however, since Telethon's approach probably won't work for us. Preferably, it should not spawn any tasks to do its job, and it should enable the user to do a one-shot pulse (e.g. "set as typing" but don't clear the state, just let it fade away).
• Updates
  • [x] run_until_disconnected. run_until_disconnected.
  • [x] catch_up. This is automatic when the user chooses to do so in the Client's Config, and when gaps occur. It does not make sense to call it at any other time (…except to "show interest", but that may be implemented differently).
• Bots
  • [x] inline_query. inline_query.
• Buttons
  • [ ] build_reply_markup. Not yet implemented. Note that this should belong in InputMessage.
• Account
  • [ ] takeout. Not yet implemented. We probably want to deviate from how Telethon does it (which is a very dirty hack to replace what invoke does).
  • [ ] end_takeout. Not yet implemented.
• Additional items
  • [ ] Future proofing (https://github.com/Lonami/grammers/issues/4#issuecomment-774568291)

Skipped methods and why:

• Auth
  • start. Too high level. grammers-client is a library, not an application, and the login flow is something applications should decide.
  • qr_login. May be added if there's enough demand for it, but otherwise the implementation is pretty simple.
  • is_connected. If you have a Client, you're connected. If you're not connected, sending requests will fail. I don't think it's worth adding a method to check for connectivity, but I am not against it if there's a solid reason for it.
  • disconnected. It's a future that behaves like run_until_disconnected.
  • loop. grammers does not hold any "event loop" or "executor" inside of it.
  • set_proxy. Is changing proxies live something desirable? Would it complicate the code too much if added (once proxies are supported)?
• Downloads
  • download_file. Too low level, and download_media already serves its purpose.
• Dialogs
  • conversation. Way too much to add. The current implementation in Telethon is quite limitting, and in Rust it may even be harder to get a similar feel with little benefit. Finite State Machines are more than enough, and one of the (if not the) most flexible approaches.
• Users
  • get_input_entity. There is no persistent cache, so this method doesn't serve any use. Furthermore, input entities are abstracted away in grammers.
  • get_peer_id. Not very useful without a persistent cache (for example, for usernames). A PackedChat or Chat already contains the ID.
• Parse Mode
  • parse_mode. A client-wide parse-mode behaves pretty much like "global state" in Telethon which is not desirable in grammers (it even affects Message attached to the TelegramClient in Telethon). Instead, each Message decides how it should be formatted.
• Updates
  • on. Decorators are nice and all, but in Telethon they rely on global state, which is harder to achieve in grammers. If it can be made pretty enough and to work well enough, I may consider adding this feature.
  • add_event_handler. Callbacks are not rusty.
  • remove_event_handler. If there are no event handlers, there is nothing to remove.
  • list_event_handlers. If there are no event handlers, there is nothing to list.

For the get_ variants (get_messages, get_dialogs, …), the iter_ methods are more than enough. Users who need a Vec can build it on their own (and decide what happens if there's an error midway through building the list rather than throwing it all away).

[Lonami]

Something that's just as important is reviewing the errors that are exposed through the public interface. For this, it might be a good idea to pretend we're a user of the library, and go through the documentation of the library built offline to see how one would use it.

[Lonami]

The new-type pattern should probably be used for all the iterators, so that they can be exposed from the grammers_client::client module. The methods in the Client struct would then point the user to these to instruct them how to configure them.

[Lonami]

Future proofing should be taken into consideration.

[Lonami]

Perhaps taking AsRef<R: RemoteCall> would enable people to send requests from things like Box<dyn RemoteCall>, needs testing.

[pickfire]

@Lonami Why do we need Box<dyn RemoteCall>? Do we not know all the telegram APIs in advance such that we need boxing to do it?

[Lonami]

I don't need it, but someone might. Just like std::fs APIs take an AsRef<Path>, it might be a good idea to do something similar for more flexibility.

[pickfire]

@Lonami Shouldn't we leave it until someone needs it? I think that is maybe a bit too much as of now.

[Lonami]

It's just changing fn invoke<R: RemoteCall>(&self, request: &R) for fn invoke<R: AsRef<RemoteCall>>(&self, request: R). Why are you so opposed to it?

[DdoSseRr]

is it possible to use telethon's sessions ?

[Lonami]

Not directly, and direct support is not planned. Regardless, that's out of scope for this issue. Which is probably safe to close in any case.