Preliminary introduction to Pydoc modules and distutils modules in Python

Pydoc

Ka-ping Yee has created a fairly well-known module, called Pydoc (in contrast: Pydoc can do anything perldoc can do, and do better, more beautiful:-). For Python 2.1来, Pydoc (and the inspect it supports) are part of the standard library. For users using Python 1.5.2, 1.6, or 2.0, downloading and installing Pydoc is simple-download now (see Resources).

Python has some semi-formal documentation standards as a background material for any beginner who reads this python article. These standards do not attempt to unduly limit the developer, but rather provide developers with "a clear way to write documents." "Fortunately, Python developers often write documents that are much better than typical developers who use other languages," he said.

The main factor in the "good" Python documentation is the use of so-called "docstring". Although docstring is actually a variable called _DOC_, there is still a common use for creating shortcuts to them: Simply place a simple string enclosed in quotation marks (Sanchong) in the head of the module, function Def, class definition, or method def. In addition, there are several "magic" variable names near the standard module level that are often used. Although those document rules are less formal, almost all third-party modules and standard module documents use the same pattern. Let's look at a simplified example that uses most of the elements:
Listing 1: module mymod.py with typical documentation

#!/usr/bin/python "" Show off features of [Pydoc] Modulethis is a silly module todemonstrate docstrings "" "__author__ = ' Dav ID Mertz ' __version__= ' 1.0 ' __nonsense__ = ' Jabberwocky ' class MyClass: ""  demonstrate class Docstrings "" "  def _ _init__ (self, Spam=1, eggs=2): "" "    Set default attribute values only    Keyword arguments:    spam―a processed MEA T product    eggs―a fine Breakfast for lumberjacks    "" "    self.spam = spam    Self.eggs = eggs

The Pydoc module leverages the conventions of Python documentation and uses some useful knowledge about Python import, inheritance, and other similar. In addition, Pydoc has the absolute gift of being able to use it in different modes of operation (see more information about the argument right away). Let's take a moment to look at the usage of the Manpage style invoked through the OS command line.

Let's say you've installed the above-mentioned module Mymod on your system, but don't know what it's useful for (not many in the example). You can read the source code, but a simpler approach might be:
Listing 2: Getting a ' manpage ' style document

% pydoc.py Mymodpython Library documentation:module mymodname  mymod-show off features of [Pydoc] Modulefile  /ar Ticles/scratch/cp18/mymod.pydescription This was  a silly module to  demonstrate docstringsclasses  MyClass  Class MyClass   | Demonstrate class docstrings   |   | __init__ (Self, spam=1, eggs=2)   |   Set default attribute values only   |   |   Keyword arguments:   |   Spam―a processed meat Product   |   Eggs―a Fine Breakfast for lumberjacksdata  __author__ = ' David mertz '  __file__ = './mymod.pyc '  __name__ = ' Mymod '  __nonsense__ = ' Jabberwocky '  __version__ = ' 1.0 ' version  1.0AUTHOR  David Mertz

Depending on the specific platform and installation process, the above sample may appear in a text viewer that allows scrolling, searching, and highlighting certain keywords. For a simple example like this, it's just a little better than purely reading the source code. However, consider a simple example like this:
Listing 3: Checking the inheritance structure of a class

% cat mymod2.pyfrom mymod import myclassclass MyClass2 (MyClass): "" "Child Class" "  def foo (self):    pass% pydoc.py mymod2. Myclass2python Library documentation:class MyClass2 in Mymod2class MyClass2 (mymod. MyClass) | Child Class | | __init__ (self, spam=1, eggs=2) from Mymod. MyClass | | Foo (self)

In this quick report, we know that MyClass2 has the __init__ () and Foo () methods (and the corresponding arguments), which are implemented by the class itself, and which other methods are inherited (and where the inherited class is located).

Another wonderful feature similar to Manpage is the-K option to search for keywords in the module. For example:
Listing 4: Locating the appropriate module for the task

% pydoc.py-k uuencodeuu-implementation of the UUencode and UUDecode functions.% pydoc.py Uupython Library Documentation : module Uuname  uu-implementation of the UUencode and UUDecode functions.[ ...]

Pydoc in addition to its command-line usage, there are four other "modes" that can display the same document being generated.

Shell mode: In the Python interactive shell, you can import Pydoc's help () function, which allows you to get assistance for any object without leaving the interactive session. You can also enter the interactive help interpreter by entering only one. For example:

Interactive help interpreter in Inventory 5:shell mode

  #-------Interactive shell with help enhancements------#  >>> from pydoc Import help  >>> Import UU  >>> Help (Uu.test) Help on  function test in module UU:  Test ()   Uuencode/uudecode main program  >>>  Help Welcome to Python 2.0! The online Help utility.  [... introductory message about help Shell ...]  Help>

• Web server mode: With the-p option only, the Pydoc will be self-booting on LOCALHOST as a simple Web server. You can use any Web browser to browse all modules that are already installed on your existing operating system. The home page of this server is a list of modules that are grouped according to the directory (and the bold color blocks supported by the browser). In addition, each module in which you view its documentation is also widely distributed with its imported functions, methods, and links to any module.
• HTML Builder Mode: the-W option generates an HTML document page for any document that Pydoc can archive. These pages are essentially the same as the pages you might browse in Web server mode, but the pages are static, can be archived, transferred, and so on.
• TK Browser mode:-G option will create a "graphical help browser" similar to Xman or Tkman style. ”

Distutils

For Python 1.6来, the Distutils package has become part of the standard Python library. The Distutils package has two purposes. On the one hand, Distutils wants to make it easy for end users to find the process of installing new modules, packages, and tools consistent. On the other hand, Distutils also wants developers of new modules, packages, and tools to find it easy to create these easy-to-install bundles. Let's take a brief look at these two aspects.

In the simplest case, the developer will have chosen to create the installer for your particular platform. If this is the case, you don't really need to know the existence of distutils at all. Currently, Distutils can create RPMs for RPM-enabled Linux systems and create Windows EXE installers for Win32 systems. While these two platforms are the protagonists, there are other platforms, or developers may already have a workaround for your platform (or have the time and interest to create an installer).

Although there is no simple example, fortunately the next good example is not too complicated. Suppose you get a source code bundle that supports Distutils, you can rely on a lot of things (of course, under all normal circumstances). The archive file for the distribution package must be in the standard archive format-usually in. zip format or. tgz/. tar.gz format (occasionally, the. tbz format or tar. Z format,. Sit format support will soon be added to MacOS). Most of the time, Windows users use zip format files, while Linux/unix users use tarball format files. However, it is not difficult to unpack most of the file formats on most platforms. Once you unpack the archive file, you get a collection of files that are stored in a directory with the same name as the archive file. For example:
Listing 6: Unpacking a [distutils] archive file

E:\archive\devel>unzip-q DISTUTILS-1_0_2.ZIPE:\ARCHIVE\DEVEL>CD distutils-1.0.2e:\archive\devel\ Distutils-1.0.2>lsthe volume label in Drive E is ARCHIVE. The Volume Serial number is e825:c814. Directory of E:\Archive\devel\Distutils-1.0.2 6-14-01  0:38a   
 
  
   
        0.6-14-01  0:38a   
  
   
    
         0.. 5-03-01  6:30p   15355      0 CHANGES.txt 5-03-01  6:32p   
   
    
     
          0 distutils 5-03-01  6:32p   
    
     
      
           0 doc 5-03-01  6:32p   
     
      
       
            0 examples10-02-00 11:47p    373      0 manifest.in 5-03-01  6:32p   
      
       
         0 Misc 5-03-01 6:32p 496 0 pkg-info 4-20-01 2:30p 14407 0 README.txt 6-29-00 11:45p 161 5 0 setup.cfg 5-03-01 6:17p 1120 0 setup.py 4-20-01 2:29p 9116 0 TODO 4-11-00 9:40p 836 0 USAGE.txt 
       
     
    
   
  
 
      
     
    
   
  

Most module distribution packages have fewer files and directories than are shown in this example. All you really need is the file setup.py, which contains the installation instructions. But in fact, everyone agrees that there are other files in the directory so that setup.py has something to install. Here, what you need to do is:

  e:\archive\devel\distutils-1.0.2> python setup.py Install

At least that's what you should do. If there is a problem, please read the README.txt or README file (most likely also included in setup.py). Then, check out Greg Ward's installing Python Modules documentation. (see Resources).

What's the next thing to do? You can guess by name, setup.py is actually just a normal Python script, so you can do anything when it runs. In most cases, however, setup.py will have a fairly fixed format. It might look like this:
Listing 7: Minimal setup.py installation script

#!/usr/bin/env python "" "Setup script for the sample #1 module distribution: Single  top-level pure python module, named Explicitly in  ' Py_modules '. "" " From Distutils.core import setupsetup (# distribution Meta-data    name = "Sample",    Version = "1.0",    Description = "Distutils Sample distribution #1", # Description of modules and packages in the distribution    py_modules = [' sample '],   )

The real work here is implemented by the imported distutils, especially by the setup () function. Basically, the setup () function takes a set of named variables that contain a list of things that need to be installed (with the exception of Py_modules and possibly packages or ext_modules or something else).

The magic of Distutils is to take advantage of the exact same setup.py files that are used during installation when creating a module distribution package. Once you--the module developer--Creates a setup.py script (or possibly ' setup.cfg ' or other extension) that specifies what needs to be installed, all that is required to create the bundle is (step or steps):
Listing 8: Creating a Module bundle

% python setup.py sdist% python setup.py bdist_wininst% python setup.py bdist_rpm

Depending on the specific bundle you specify, you will create a standard archive file (tarball or zip format file, depending on the platform type) or a complete installer (as discussed above).

To combine the two together

Although we have not yet fully achieved this goal, Python has gradually become one of the easiest programming languages to use, and it is one of the easiest programming communities to use. While some of the new tools have some flaws to overcome, the requirement for Python to be transparent to the user has already been achieved in the general sense.

