Example code in the documentation does not work

[txtsd]

On this page
This bit of code

import pydle

client = pydle.Client('MyBot')
# Client.connect() is a coroutine.
await client.connect('irc.freenode.net', tls=True)
client.handle_forever()

fails with

  File "client.py", line 16
    await client.connect('irc.freenode.net', tls=True, tls_verify=True)
    ^
SyntaxError: 'await' outside function

and the on_join bits in the following examples fail with

Failed to execute on_raw_join handler.
Traceback (most recent call last):
  File "<snip>/lib/python3.8/site-packages/pydle/client.py", line 422, in on_raw
    await handler(message)
  File "<snip>/lib/python3.8/site-packages/pydle/features/ircv3/ircv3_1.py", line 99, in on_raw_join
    await super().on_raw_join(message)
  File "<snip>/lib/python3.8/site-packages/pydle/features/whox.py", line 15, in on_raw_join
    await super().on_raw_join(message)
  File "<snip>/lib/python3.8/site-packages/pydle/features/rfc1459/client.py", line 581, in on_raw_join
    await self.on_join(channel, nick)
  File "client.py", line 14, in on_join
    await self.message(channel, 'Hey there, {user}!', user=user)
TypeError: message() got an unexpected keyword argument 'user'
Failed to execute on_raw_join handler.

[txtsd]

Examples further down don't work either. Who wrote these? ಠ_ಠ

[theunkn0wn1]

Ok, I see why the examples don't work as-is. They would work from a modern IPython shell but that isn't a valid excuse.

What happened here Is these documents were updated from old, legacy syntax.

The biggest issue I see here is await used outside a function. this ought to be an asyncio.run by modern standards. (Though it will likely resolve to asyncio.get_event_loop.run_until_complete since we support python3.6 .

the unexpected keyword argument is interesting, and is a distinct failure. I will need to investigate why that doesn't work, as far as I am aware I didn't need to touch that part of the example. It appears user= should be target= though im not sure thats going to work given the signature of that function.

    async def message(self, target, message):

I will set aside some time this week to review these examples.

Optimally these examples would be in their own files and somehow imported into the built docs, so they can actually be tested (which is the subject of #78 )

[txtsd]

In the asynchronous example, the is_admin function refers to a source variable that is not defined in the function. And the self.message(target, '{source}: You are an administrator.', source=source) line is also broken, it should just be '<string>'.format(source), not an argument to the function.

Thanks for addressing it.

[theunkn0wn1]

In the asynchronous example, the is_admin function refers to a source variable that is not defined in the function.

Thats unfortunate. Perhaps a clean rewrite of these is in order.
source probably was intended to be nickname in that example.

I have noticed similar issues in other modules of pydle where names are referenced before assignment and similar errors and have been fixing them as I have become aware. This is likely another case. As time allows I will investigate these examples and come up with a remediation.

[txtsd]

I have noticed similar issues in other modules of pydle where names are referenced before assignment and similar errors and have been fixing them as I have become aware. This is likely another case. As time allows I will investigate these examples and come up with a remediation.

Sounds good. I'd open a PR myself, but I'm invested in another project atm.