Version 2 wishlist

I've been brewing ideas for v2 for a while now (probably over a year), and I started implementing some of these ideas in a separate branch (completely rewriting the code). Inevitably, the master branch kept getting worked on, and it eventually fell apart.

So now I'm trying to reboot some of my ideas, but I'll take a separate approach to implementing them: I'll implement almost everything that can be done without making breaking changes, and then I'll move the project into a state of v2, where we can properly progress towards a cleaner API. In general, I'd much rather have a stable, minimal API, than an unstable, comprehensive API!

I've tried to assemble a list of major things I'd like to see before making breaking changes:

• Use flit as our build system (see #382)
• Use black for formatting (see #386)
• Refactor code into logical, separate files (client.py is far too large)
  • Would help us to make proper unit tests
• Set up integration tests using something like VCR.py
• Clean up documentation
  • Fix setup (tracked in #391)
  • Make @carpedm20 set up the webhook, so that tag creation / deletion is tracked as well
  • API rundown (Use Google Docstring Style)
  • Introduction overview overhaul
  • Investigate tools for detecting docstring errors and spelling mistakes
• Inline examples
• More detailed examples (recommends good practice too)
• API coherence (fetchThreadMessages can't fetch "system" messages / events)

And a list of major things I'd like to change:

• Drop Python 2 support (It'll probably reach it's EOL before we get everything done 😁)
• Use type hints
  • Improve documentation with sphinx-autodoc-typehints
• Consider async options
  • See sphinxcontrib-trio for documentation improvements on this.
• Declare a proper public API. See trio as a reference to a project that fullfulls this promise (e.g. using _ before methods and filenames)
• Declare a concise API (e.g. document expected exceptions)
  • Using datetimes, see #278, is a subtask of this
• Use snake_cased method names like PEP8 suggests
• Fix logging (see #258)
• Make a distinction between models, like Message, and what you can send, as parameters in send. Though combining these sound good idea in theory, it's really messy in practice, and not really that useful.
• Make a distinction between user created models and recieved models
  • Building upon this idea, we can move a lot of implementations into the model instead of a central client. For example, I'd like to be able to do something like:

    message = Message(id="123", client=client)  # Does not make an external call (since you don't need to, to interact with the message)
    message.react(None)
    assert not hasattr(message, "text")
    # Or alternatively:
    message = client.get_message("123")  # Makes an external call, and returns `MessageData`, a subclass of `Message`
    message.react("👍")
    assert hasattr(message, "text")
    

But anyway, it's late, and I'm rambling, and a lot of the later bullet points are still pretty abstract ideas. We should focus on the most pressing points first 😁.

If you have something you'd like to put on the wishlist, or would like to point the project in a different direction, suggest away, I'd love to hear what you have to say! 😊