mirror of
https://github.com/python/cpython.git
synced 2025-08-04 08:59:19 +00:00
The third and final doc-string sweep by Ka-Ping Yee.
The attached patches update the standard library so that all modules have docstrings beginning with one-line summaries. A new docstring was added to formatter. The docstring for os.py was updated to mention nt, os2, ce in addition to posix, dos, mac.
This commit is contained in:
Guido van Rossum
parent
54f22ed30b
commit
e7b146fb3b
29 changed files with 891 additions and 778 deletions
207
Lib/sunau.py
207
Lib/sunau.py
|
|
@ -1,106 +1,107 @@
|
|||
# Stuff to parse Sun and NeXT audio files.
|
||||
#
|
||||
# An audio consists of a header followed by the data. The structure
|
||||
# of the header is as follows.
|
||||
#
|
||||
# +---------------+
|
||||
# | magic word |
|
||||
# +---------------+
|
||||
# | header size |
|
||||
# +---------------+
|
||||
# | data size |
|
||||
# +---------------+
|
||||
# | encoding |
|
||||
# +---------------+
|
||||
# | sample rate |
|
||||
# +---------------+
|
||||
# | # of channels |
|
||||
# +---------------+
|
||||
# | info |
|
||||
# | |
|
||||
# +---------------+
|
||||
#
|
||||
# The magic word consists of the 4 characters '.snd'. Apart from the
|
||||
# info field, all header fields are 4 bytes in size. They are all
|
||||
# 32-bit unsigned integers encoded in big-endian byte order.
|
||||
#
|
||||
# The header size really gives the start of the data.
|
||||
# The data size is the physical size of the data. From the other
|
||||
# parameter the number of frames can be calculated.
|
||||
# The encoding gives the way in which audio samples are encoded.
|
||||
# Possible values are listed below.
|
||||
# The info field currently consists of an ASCII string giving a
|
||||
# human-readable description of the audio file. The info field is
|
||||
# padded with NUL bytes to the header size.
|
||||
#
|
||||
# Usage.
|
||||
#
|
||||
# Reading audio files:
|
||||
# f = sunau.open(file, 'r')
|
||||
# where file is either the name of a file or an open file pointer.
|
||||
# The open file pointer must have methods read(), seek(), and close().
|
||||
# When the setpos() and rewind() methods are not used, the seek()
|
||||
# method is not necessary.
|
||||
#
|
||||
# This returns an instance of a class with the following public methods:
|
||||
# getnchannels() -- returns number of audio channels (1 for
|
||||
# mono, 2 for stereo)
|
||||
# getsampwidth() -- returns sample width in bytes
|
||||
# getframerate() -- returns sampling frequency
|
||||
# getnframes() -- returns number of audio frames
|
||||
# getcomptype() -- returns compression type ('NONE' or 'ULAW')
|
||||
# getcompname() -- returns human-readable version of
|
||||
# compression type ('not compressed' matches 'NONE')
|
||||
# getparams() -- returns a tuple consisting of all of the
|
||||
# above in the above order
|
||||
# getmarkers() -- returns None (for compatibility with the
|
||||
# aifc module)
|
||||
# getmark(id) -- raises an error since the mark does not
|
||||
# exist (for compatibility with the aifc module)
|
||||
# readframes(n) -- returns at most n frames of audio
|
||||
# rewind() -- rewind to the beginning of the audio stream
|
||||
# setpos(pos) -- seek to the specified position
|
||||
# tell() -- return the current position
|
||||
# close() -- close the instance (make it unusable)
|
||||
# The position returned by tell() and the position given to setpos()
|
||||
# are compatible and have nothing to do with the actual postion in the
|
||||
# file.
|
||||
# The close() method is called automatically when the class instance
|
||||
# is destroyed.
|
||||
#
|
||||
# Writing audio files:
|
||||
# f = sunau.open(file, 'w')
|
||||
# where file is either the name of a file or an open file pointer.
|
||||
# The open file pointer must have methods write(), tell(), seek(), and
|
||||
# close().
|
||||
#
|
||||
# This returns an instance of a class with the following public methods:
|
||||
# setnchannels(n) -- set the number of channels
|
||||
# setsampwidth(n) -- set the sample width
|
||||
# setframerate(n) -- set the frame rate
|
||||
# setnframes(n) -- set the number of frames
|
||||
# setcomptype(type, name)
|
||||
# -- set the compression type and the
|
||||
# human-readable compression type
|
||||
# setparams(tuple)-- set all parameters at once
|
||||
# tell() -- return current position in output file
|
||||
# writeframesraw(data)
|
||||
# -- write audio frames without pathing up the
|
||||
# file header
|
||||
# writeframes(data)
|
||||
# -- write audio frames and patch up the file header
|
||||
# close() -- patch up the file header and close the
|
||||
# output file
|
||||
# You should set the parameters before the first writeframesraw or
|
||||
# writeframes. The total number of frames does not need to be set,
|
||||
# but when it is set to the correct value, the header does not have to
|
||||
# be patched up.
|
||||
# It is best to first set all parameters, perhaps possibly the
|
||||
# compression type, and then write audio frames using writeframesraw.
|
||||
# When all frames have been written, either call writeframes('') or
|
||||
# close() to patch up the sizes in the header.
|
||||
# The close() method is called automatically when the class instance
|
||||
# is destroyed.
|
||||
"""Stuff to parse Sun and NeXT audio files.
|
||||
|
||||
An audio consists of a header followed by the data. The structure
|
||||
of the header is as follows.
|
||||
|
||||
+---------------+
|
||||
| magic word |
|
||||
+---------------+
|
||||
| header size |
|
||||
+---------------+
|
||||
| data size |
|
||||
+---------------+
|
||||
| encoding |
|
||||
+---------------+
|
||||
| sample rate |
|
||||
+---------------+
|
||||
| # of channels |
|
||||
+---------------+
|
||||
| info |
|
||||
| |
|
||||
+---------------+
|
||||
|
||||
The magic word consists of the 4 characters '.snd'. Apart from the
|
||||
info field, all header fields are 4 bytes in size. They are all
|
||||
32-bit unsigned integers encoded in big-endian byte order.
|
||||
|
||||
The header size really gives the start of the data.
|
||||
The data size is the physical size of the data. From the other
|
||||
parameter the number of frames can be calculated.
|
||||
The encoding gives the way in which audio samples are encoded.
|
||||
Possible values are listed below.
|
||||
The info field currently consists of an ASCII string giving a
|
||||
human-readable description of the audio file. The info field is
|
||||
padded with NUL bytes to the header size.
|
||||
|
||||
Usage.
|
||||
|
||||
Reading audio files:
|
||||
f = sunau.open(file, 'r')
|
||||
where file is either the name of a file or an open file pointer.
|
||||
The open file pointer must have methods read(), seek(), and close().
|
||||
When the setpos() and rewind() methods are not used, the seek()
|
||||
method is not necessary.
|
||||
|
||||
This returns an instance of a class with the following public methods:
|
||||
getnchannels() -- returns number of audio channels (1 for
|
||||
mono, 2 for stereo)
|
||||
getsampwidth() -- returns sample width in bytes
|
||||
getframerate() -- returns sampling frequency
|
||||
getnframes() -- returns number of audio frames
|
||||
getcomptype() -- returns compression type ('NONE' or 'ULAW')
|
||||
getcompname() -- returns human-readable version of
|
||||
compression type ('not compressed' matches 'NONE')
|
||||
getparams() -- returns a tuple consisting of all of the
|
||||
above in the above order
|
||||
getmarkers() -- returns None (for compatibility with the
|
||||
aifc module)
|
||||
getmark(id) -- raises an error since the mark does not
|
||||
exist (for compatibility with the aifc module)
|
||||
readframes(n) -- returns at most n frames of audio
|
||||
rewind() -- rewind to the beginning of the audio stream
|
||||
setpos(pos) -- seek to the specified position
|
||||
tell() -- return the current position
|
||||
close() -- close the instance (make it unusable)
|
||||
The position returned by tell() and the position given to setpos()
|
||||
are compatible and have nothing to do with the actual postion in the
|
||||
file.
|
||||
The close() method is called automatically when the class instance
|
||||
is destroyed.
|
||||
|
||||
Writing audio files:
|
||||
f = sunau.open(file, 'w')
|
||||
where file is either the name of a file or an open file pointer.
|
||||
The open file pointer must have methods write(), tell(), seek(), and
|
||||
close().
|
||||
|
||||
This returns an instance of a class with the following public methods:
|
||||
setnchannels(n) -- set the number of channels
|
||||
setsampwidth(n) -- set the sample width
|
||||
setframerate(n) -- set the frame rate
|
||||
setnframes(n) -- set the number of frames
|
||||
setcomptype(type, name)
|
||||
-- set the compression type and the
|
||||
human-readable compression type
|
||||
setparams(tuple)-- set all parameters at once
|
||||
tell() -- return current position in output file
|
||||
writeframesraw(data)
|
||||
-- write audio frames without pathing up the
|
||||
file header
|
||||
writeframes(data)
|
||||
-- write audio frames and patch up the file header
|
||||
close() -- patch up the file header and close the
|
||||
output file
|
||||
You should set the parameters before the first writeframesraw or
|
||||
writeframes. The total number of frames does not need to be set,
|
||||
but when it is set to the correct value, the header does not have to
|
||||
be patched up.
|
||||
It is best to first set all parameters, perhaps possibly the
|
||||
compression type, and then write audio frames using writeframesraw.
|
||||
When all frames have been written, either call writeframes('') or
|
||||
close() to patch up the sizes in the header.
|
||||
The close() method is called automatically when the class instance
|
||||
is destroyed.
|
||||
"""
|
||||
|
||||
# from <multimedia/audio_filehdr.h>
|
||||
AUDIO_FILE_MAGIC = 0x2e736e64
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue