| msg297039 - (view) |
Author: tom kronmiller (tom kronmiller) |
Date: 2017-06-27 14:23 |
| It is difficult to learn what decorators there are because there is no single index which lists all of them (at least, I have been unable to find one). Instead, one must stumble across them while reading library module documentation. An index listing the decorators with a short description would be really helpful (to me, at least). Thanks. |
|
|
| msg297204 - (view) |
Author: Brett Cannon (brett.cannon) *  |
Date: 2017-06-28 17:53 |
| Why do you want an index of *just* decorators? The documentation is structured so you look for the module that probably contains a solution to your problem and then you see what the module may have (which may have a solution that isn't a decorator). Jumping straight to a list of just decorators means you would miss out on any other solution that happens to not be a decorator. |
|
|
| msg297243 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2017-06-29 02:14 |
| This request doesn't make sense to me. Decorators are an implementation technique and not really a topic unto themselves. FWIW, Guido recently rejected a request to create a listing of all the command line tools. Python docs are primarily organized by modules of related tools rather than by their implementation technique. |
|
|
| msg297295 - (view) |
Author: tom kronmiller (tom kronmiller) |
Date: 2017-06-29 19:08 |
| I would not object if there was an index which contained the decorators among other things, but I have found it difficult in practice to discover things like @staticmethod and @contextmanager. Just as I browse the index of library modules to for insight as to what it provides, I would like to browse the decorators for insight as to problems that have been solved using them. |
|
|
| msg297419 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2017-06-30 15:29 |
| Hmm. All the dunder methods are listed in the index on the '_' page. It would kind of be consistent to have an '@' page. Not sure what would be needed to make that happen though (might be a sphinx level thing). |
|
|
| msg297425 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2017-06-30 15:42 |
| Both staticmethod and contextmanager are in the index under "S" and "C". But if you mean they were hard to discover, having them under a list of decorators wouldn't have necessarily helped since, as we pointed out, you may get misled to look for a decorator when in fact there was a better solution that wasn't a decorator. I'm closing this as "not a bug" since listing everything twice -- once under its name and once under its type/expected usage -- is just going to lead to unwieldy lists that are ridiculously long that no one is going to peruse. |
|
|
| msg297426 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2017-06-30 15:42 |
| And thanks for at least bringing the idea forward, Tom. |
|
|