grammers
grammers copied to clipboard
Friendly methods
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
andbot_sign_in
- [x]
sign_up
.sign_up
. - [x]
log_out
.sign_out
. - [ ]
edit_2fa
. Not yet implemented.
- [x]
- 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"?
- [x]
- 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
andsearch_all_messages
. - [x]
pin_message
.pin_message
. - [x]
unpin_message
.unpin_message
. - [x]
send_read_acknowledge
.mark_as_read
.
- [x]
- Uploads
- [x]
send_file
.send_message
already serves its purpose. - [x]
upload_file
.upload_file
andupload_stream
.
- [x]
- Downloads
- [x]
download_media
.download_media
. - [ ]
download_profile_photo
. Not yet implemented. Probably should be covered bydownload_media
instead though, rather than being its own method. - [x]
iter_download
.iter_download
.
- [x]
- 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
.
- [x]
- 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
andunpack_chat
.
- [x]
- 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 ingrammers
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).
- [x]
- Updates
- [x]
run_until_disconnected
.run_until_disconnected
. - [x]
catch_up
. This is automatic when the user chooses to do so in theClient
'sConfig
, 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).
- [x]
- Bots
- [x]
inline_query
.inline_query
.
- [x]
- Buttons
- [ ]
build_reply_markup
. Not yet implemented. Note that this should belong inInputMessage
.
- [ ]
- Account
- [ ]
takeout
. Not yet implemented. We probably want to deviate from how Telethon does it (which is a very dirty hack to replace whatinvoke
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 aClient
, 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 likerun_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, anddownload_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 ingrammers
. -
get_peer_id
. Not very useful without a persistent cache (for example, for usernames). APackedChat
orChat
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 ingrammers
(it even affectsMessage
attached to theTelegramClient
in Telethon). Instead, eachMessage
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 ingrammers
. 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).
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.
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.
Future proofing should be taken into consideration.
Perhaps taking AsRef<R: RemoteCall>
would enable people to send requests from things like Box<dyn RemoteCall>
, needs testing.
@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?
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.
@Lonami Shouldn't we leave it until someone needs it? I think that is maybe a bit too much as of now.
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?
is it possible to use telethon's sessions ?
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.