Interactive demo for `attrs` code examples

[martinzugnoni]

Hello @python-attrs,

I've been using the attrs library for a while and I really like what you guys have built. We've even started using it to teach our students at https://rmotr.com/ (co-founder and teacher here) when talking about OOP and Classes as an alternative to the default usage.

While looking at the attrs by Example section I thought it would be great to provide some interactive demo that people can use to play with the library before committing to download and install it locally.

A demo is worth a thousand words 😉

I spent some time compiling all attrs examples into a Jupyter Notebook file, and adapted it in a way that we can open it with a small service we have at RMOTR to launch Jupyter environments online. No account or subscription required to use it, so it's pretty convenient for people that wants to get hands on the library with a low entrance barrier.

The result is what you can see in my fork of the repo (see the new "Demo" section): https://github.com/martinzugnoni/attrs

Do you agree that having such interactive demo would help people to know and use attrs? Let's use this issue as a kick off to start a discussion. Nothing here is written in stone and we can change everything as you wish.

I hope you guys like it, and I truly appreciate any feedback.

thanks.

[hynek]

Thank you for your kind words and bringing the good news of attrs to impressionable minds. :)

I would agree that demos and Jupyter notebooks are a great way to give an actual taste of attrs.

The coolest solution would be if we could somehow automatically translate our examples page into a Jupyter notebook.

The open question is that of ownership. I'm happy about your generous offer to host the notebook but if we link to it from our front pages, the control over it needs to remain with us. Is it technically feasible to make a workflow of auto-generation + upload on release make happen?

[martinzugnoni]

Hi @hynek! thanks for your answer.

A few points answering your questions:

• the service doesn't "host" the notebook. It reads the examples notebook file dynamically from the repository (see the DEMO.ipynb file in my fork). In a final solution this notebooks file should be merged into the original repo under @python-attrs, and we can keep it under version control as any other file in the repo. We can continue adding more examples in the future to the DEMO.ipynb notebook as well. Also, anyone cloning the attrs repo can run the example notebook locally without depending on this service.

• when the environment loads, attrs is automatically installed as a requirements so people can start using it right aways without needing to install anything (demo.yml config file is used for that).

• in my example the "Open demo" button points to my fork (under @martinzugnoni), but in the final version it should point to the original repository so we keep contributing all to the same code base. I've used my fork as an example, so you can see how it will look like when it's ready.

If you think this is a good idea, I'm happy to open a pull request and do the required small changes mentioned above.

thanks.

[martinzugnoni]

@hynek did I answer you doubts? What's the best way of moving forward with this in your opinion? I'm happy to collaborate as much as I can. Keep me posted ;-)

[hynek]

I don't even dare to ask if this is still in any way up to discussion and am just gonna close in shame. Your last message was my oldest pinned email and I was waiting for "one last feature to land so it's worth it" until… well. Sorry again! :(