如何在python中向用户显示模块和子类的文档

Question

I am trying to code up a module which has two classes. First class is called as TextProcessing

class TextProcessing(object):

    """ To carry out text processing 
    """

    def __init__(self,):
        pass

It has various methods in there for pre-processing text.

Similary other class is for other data wrangling on pre-processed data.

I am saving these two classes in a python file to make it a module.

Now lets say a user downloads this python module and would now want to run the various methods of each class.

I wanted to provide some sort of documentation about the module, methods of each class to a user when she imports the module so that she is aware of which function to call and what parameters to pass.

Think of how a scikit learn documentation is on their documentation page.

http://scikit-learn.org/stable/modules/generated/sklearn.feature_extraction.text.TfidfTransformer.html

Even the documentation we get to see when we do

help(some_python_module) 

is fine too.

Issue is I don't have a documentation page like sklearn to show documentation. And I wanted a user to know documentation of various methods she can use once she imports the module in python console.

Is there a way I can print that documentation info to the console when a user imports the module?

It can show the doc string of each Class and Method.

Answer 1

This is a very weird thing to do, but it's definitely possible .

---

The easiest thing to do is just to call help . While it's intended to be called from the interactive prompt, there's nothing stopping you from calling it from your own code.

Of course you could instead extract the docstrings (they're stored as __doc__ on every module, class, and function), textwrap them yourself, and print them out, but if you're trying to reproduce the same thing help does, that's a lot of work for no real benefit.

---

The only tricky bit is that the thing you want to invoke the help system on is "this current module". How do you refer to that? It's a bit clunky, but you have this current module's name as __name__ , so you can look it up in sys.modules .

So:

"""Helpful module"""

import sys

class Spam:
    """Classy class"""
    def eggs(self):
        "Functional function"
        return 2

help(sys.modules[__name__])

Now, when you import helpful for the first time in a session, it will print out the help .

---

Of course that will be pretty odd if someone's trying to run a script that does an import helpful , rather than doing it from an interactive session. So you may want to only do this in interactive sessions, by checking sys.flags :

if sys.flags.interactive:
    help(sys.modules[__name__])

---

What if someone does an import otherthing , and that otherthing does an import helpful ? You'll get the same help, which may be confusing.

If that's a problem, the only real option I can think of is to check whether the calling frame comes from the top-level script (and that the flags are interactive). That's pretty hacky, and something you shouldn't even consider unless you really need to, so I'll just direct you to the inspect module and hope you don't need it.