A preliminary introduction to Pydoc modules and distutils modules in Python _python

Pydoc

Ka-ping Yee has created a fairly famous module named Pydoc (in comparison: Pydoc can do anything perldoc can do, and do better and more beautiful:-). For Python 2.1来, Pydoc (and inspect that it supports) is part of the standard library. For users using the Python 1.5.2, 1.6 or 2.0 version, downloading and installing Pydoc is also easy-download now (see Resources).

As a background for any beginner who reads this python article, Python has a bit of a formal document standard. These standards do not attempt to unduly limit developers, but rather provide developers with "an obvious way to write documents." "Luckily, Python developers often write documents that are much better than typical developers who use other languages," he says.

The main reason why Python documents are "excellent" is to use so-called "docstring". Although DocString is actually just a variable called _DOC_, there is a commonly used shortcut to creating them: Simply put a simple string of (Sanchong) quotes around the head of a module, function Def, class definition, or method def. In addition, there are several near-standard module-level "Magic" variable names 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 with a typical document mymod.py

#!/usr/bin/python
"" "show off features of [Pydoc] module '
a silly module to
demonstrate docstrings
   
     "" "" ""
__author__ = ' David 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 meat product Eggs―a fine breakfast for Lumberjacks "" "
    self. Spam = spam
    Self.eggs = eggs


   

The Pydoc module leverages the conventions of the Python documentation and uses some useful knowledge about Python imports, inheritance, and other similar things. In addition, Pydoc has the absolute gift of being able to use different modes of operation (see more information about this 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 module Mymod on your system, but you don't know what it does (not much in the example). You can read the source code, but the simpler approach might be:
Listing 2: Getting the ' manpage ' style document

% pydoc.py mymod
Python Library documentation:module mymod
NAME
  mymod-show off features of [Pydoc] Module
   file
  /articles/scratch/cp18/mymod.py
DESCRIPTION This are
  a silly module to
  demonstrate docstrings
CLASSES
  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 lumberjacks
DATA
  __author__ = ' David mertz '
  __file__ = './mymod.pyc '
  __na me__ = ' Mymod '
  __nonsense__ = ' Jabberwocky '
  __version__ = ' 1.0 '
version
  1.0
AUTHOR
  David Mertz

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

% cat mymod2.py from
mymod import MyClass
class MyClass2 (MyClass): "" Child Class ""
  def foo (self):
    Pass
% pydoc.py mymod2. MyClass2
Python Library documentation:class MyClass2 in Mymod2
class MyClass2 (Mymod. MyClass)
 | Child Class
 |
 | __init__ (Self, spam=1, eggs=2) from Mymod. MyClass
 |
 | foo (self)

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

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

% pydoc.py-k uuencode
uu-implementation of the uuencode and UUDecode functions.
% pydoc.py uu
Python Library documentation:module uu
NAME
  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 that was generated.

Shell mode: In the Python interactive shell, you can import the Pydoc help () function, so that you can get assistance from any object without leaving the interactive session. You can also enter only one help into the interactive "help interpreter." For example:

The interactive help interpreter in Listing 5:shell mode

  #-------Interactive shell with help enhancements------#
  >>> ' 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! This are the online Help utility.
  [... introductory message about help Shell ...]
  Help>

• Web Server mode: With the-P option only, Pydoc will be launched as a simple Web server on LOCALHOST. You can use any Web browser to browse all modules that have been installed on an existing operating system. The home page of this server is a list of modules that are grouped according to the directory (with the eye-catching color blocks supported by the browser). In addition, each module in which you view its documentation is widely distributed with functions, methods, and links to any modules that it imports.
• HTML Builder Pattern: the-W option generates HTML document pages for any document that Pydoc can archive. These pages are essentially the same as the pages you might be browsing in Web server mode, but the pages are static, can be archived, transmitted, and so on.
• TK Browser Mode: The-G option creates a graphics help browser that is similar to the 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 the end user feel consistent and relaxed about installing new modules, packages, and tools. On the other hand, Distutils also wants to make new modules, packages, and tool developers feel comfortable creating these easy to install distribution contracts. 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 about the existence of distutils. Currently, Distutils can create rpm for Linux systems that support RPM and create Windows EXE installers for the WIN32 system. Although these two platforms are protagonists, there are other platforms, or developers may already have a workaround for your platform (or the time and interest to create a setup program).

Although there is no simplest example, fortunately the next outstanding example is not too complicated. Suppose you get a source code distribution 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 the. zip format or. tgz/. tar.gz format (occasionally. tbz format or tar. Z format,. Sit format support will soon be added to the 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, you will get a collection of files that are saved in a directory with the same name as the archive file. For example,
Listing 6: Unpack a [distutils] archive

 E:\archive\devel>unzip-q distutils-1_0_2.zip E:\ARCHIVE\DEVEL>CD
Distutils-1.0.2 E:\archive\devel\distutils-1.0.2>ls the 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 <DIR> 0.
 6-14-01 0:38a <DIR> 0.      5-03-01 6:30p 15355 0 CHANGES.txt 5-03-01 6:32p <DIR> 0 distutils 5-03-01 6:32p <DIR> 0 Doc 5-03-01 6:32p <DIR> 0 Examples 10-02-00 11:47p 373 0 manifest.in 5-03-01 6:32p <dir&      Gt 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 1615 0 Setu P.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 /pre> 

Most module distribution packages have fewer files and directories than shown in this example. All you really need is the file setup.py, which contains the installation instructions. But in fact, we all agree that there are other files in the directory, so that setup.py can have 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, read the README.txt or README file (which is probably also included in setup.py). Then, check out Greg Ward's installing Python Modules document. (see Resources).

What should we do next? You can guess by name, setup.py is just an ordinary Python script, so when it runs, it can do anything. But in most cases setup.py will have a fairly fixed format. Might look like this:
Listing 7: The smallest 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 Setup
Setup (# distribution Meta-data
    name = "Sample",
    Version = "1.0",
    Description = "Distutils Sample distribution #1",
# Description of modules and packages in the distribution
    Py_mo Dules = [' 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 (except Py_modules may have packages or ext_modules or something else).

The magic of Distutils is to create a module distribution package using exactly the same setup.py files that are used during installation. Once you--the module developer--created a setup.py script (which may also be ' setup.cfg ' or other extension) that specifies what needs to be installed, all the things you need to do to create a distribution contract are (the next step or several steps):
Listing 8: Creating a Module distribution contract

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

Depending on the specific distribution 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 haven't fully achieved our goal yet, Python has gradually become one of the easiest programming languages to use, and one of the easiest programming communities to use. While some of the new tools still have some flaws to overcome, the requirement to make Python transparent to users in the general sense has been achieved.