diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -14,7 +14,7 @@ Check :ref:`the Library Reference ` to see if there's a relevant standard library module. (Eventually you'll learn what's in the standard -library and will able to skip this step.) +library and will be able to skip this step.) For third-party packages, search the `Python Package Index `_ or try `Google `_ or @@ -92,9 +92,9 @@ .. XXX curses *is* built by default, isn't it? For Unix variants: The standard Python source distribution comes with a curses -module in the ``Modules/`` subdirectory, though it's not compiled by default -(note that this is not available in the Windows distribution -- there is no -curses module for Windows). +module in the ``Modules/`` subdirectory, though it's not compiled by default. +(Note that this is not available in the Windows distribution -- there is no +curses module for Windows.) The curses module supports basic curses features as well as many additional functions from ncurses and SYSV curses such as colour, alternative character set @@ -110,7 +110,7 @@ ------------------------------------------------- The :mod:`atexit` module provides a register function that is similar to C's -onexit. +:c:func:`onexit`. Why don't my signal handlers work? @@ -140,8 +140,8 @@ The :mod:`unittest` module is a fancier testing framework modelled on Java and Smalltalk testing frameworks. -For testing, it helps to write the program so that it may be easily tested by -using good modular design. Your program should have almost all functionality +To make testing easier, you should use good modular design in your program. +Your program should have almost all functionality encapsulated in either functions or class methods -- and this sometimes has the surprising and delightful effect of making the program run faster (because local variable accesses are faster than global accesses). Furthermore the program @@ -157,7 +157,7 @@ Once your program is organized as a tractable collection of functions and class behaviours you should write test functions that exercise the behaviours. A test -suite can be associated with each module which automates a sequence of tests. +suite that automates a sequence of tests can be associated with each module. This sounds like a lot of work, but since Python is so terse and flexible it's surprisingly easy. You can make coding much more pleasant and fun by writing your test functions in parallel with the "production code", since this makes it @@ -273,7 +273,7 @@ time.sleep(10) -Instead of trying to guess how long a :func:`time.sleep` delay will be enough, +Instead of trying to guess a good delay value for :func:`time.sleep`, it's better to use some kind of semaphore mechanism. One idea is to use the :mod:`Queue` module to create a queue object, let each thread append a token to the queue when it finishes, and let the main thread read as many tokens from the @@ -284,10 +284,10 @@ --------------------------------------------------------- Use the :mod:`Queue` module to create a queue containing a list of jobs. The -:class:`~Queue.Queue` class maintains a list of objects with ``.put(obj)`` to -add an item to the queue and ``.get()`` to return an item. The class will take -care of the locking necessary to ensure that each job is handed out exactly -once. +:class:`~Queue.Queue` class maintains a list of objects and has a ``.put(obj)`` +method that adds items to the queue and a ``.get()`` method to return them. +The class will take care of the locking necessary to ensure that each job is +handed out exactly once. Here's a trivial example:: @@ -503,7 +503,7 @@ :func:`os.read` is a low-level function which takes a file descriptor, a small integer representing the opened file. :func:`os.popen` creates a high-level file object, the same type returned by the built-in :func:`open` function. -Thus, to read n bytes from a pipe p created with :func:`os.popen`, you need to +Thus, to read n bytes from a pipe *p* created with :func:`os.popen`, you need to use ``p.read(n)``. @@ -522,9 +522,9 @@ Warning: in general it is unwise to do this because you can easily cause a deadlock where your process is blocked waiting for output from the child while -the child is blocked waiting for input from you. This can be caused because the -parent expects the child to output more text than it does, or it can be caused -by data being stuck in stdio buffers due to lack of flushing. The Python parent +the child is blocked waiting for input from you. This can be caused by the +parent expecting the child to output more text than it does or by data being +stuck in stdio buffers due to lack of flushing. The Python parent can of course explicitly flush the data it sends to the child before it reads any output, but if the child is a naive C program it may have been written to never explicitly flush its output, even if it is interactive, since flushing is @@ -673,7 +673,7 @@ sys.stdout.write(httpobj.getfile().read()) Note that in general for percent-encoded POST operations, query strings must be -quoted using :func:`urllib.quote`. For example to send name="Guy Steele, Jr.":: +quoted using :func:`urllib.quote`. For example, to send name="Guy Steele, Jr.":: >>> from urllib import quote >>> x = quote("Guy Steele, Jr.") @@ -689,19 +689,8 @@ .. XXX add modern template languages -There are many different modules available: - -* HTMLgen is a class library of objects corresponding to all the HTML 3.2 markup - tags. It's used when you are writing in Python and wish to synthesize HTML - pages for generating a web or for CGI forms, etc. - -* DocumentTemplate and Zope Page Templates are two different systems that are - part of Zope. - -* Quixote's PTL uses Python syntax to assemble strings of text. - -Consult the `Web Programming wiki pages -`_ for more links. +You can find a collection of useful links on the `Web Programming wiki page +`_. How do I send mail from a Python script? @@ -730,7 +719,7 @@ server.quit() A Unix-only alternative uses sendmail. The location of the sendmail program -varies between systems; sometimes it is ``/usr/lib/sendmail``, sometime +varies between systems; sometimes it is ``/usr/lib/sendmail``, sometimes ``/usr/sbin/sendmail``. The sendmail manual page will help you out. Here's some sample code:: @@ -797,7 +786,7 @@ The :mod:`marshal` module provides very fast ways to store noncircular basic Python types to files and strings, and back again. Although marshal does not do fancy things like store instances or handle shared references properly, it does -run extremely fast. For example loading a half megabyte of data may take less +run extremely fast. For example, loading a half megabyte of data may take less than a third of a second. This often beats doing something more complex and general such as using gdbm with pickle/shelve.