Remove docs for xreadlines, mpz, rotor
This commit is contained in:
Andrew M. Kuchling
parent
e723863ba1
commit
ab459f71d6
|
|
@ -203,9 +203,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
|
||||||
lib/libcrypto.tex \
|
lib/libcrypto.tex \
|
||||||
lib/libmd5.tex \
|
lib/libmd5.tex \
|
||||||
lib/libsha.tex \
|
lib/libsha.tex \
|
||||||
lib/libmpz.tex \
|
|
||||||
lib/libhmac.tex \
|
lib/libhmac.tex \
|
||||||
lib/librotor.tex \
|
|
||||||
lib/libstdwin.tex \
|
lib/libstdwin.tex \
|
||||||
lib/libsgi.tex \
|
lib/libsgi.tex \
|
||||||
lib/libal.tex \
|
lib/libal.tex \
|
||||||
|
|
@ -278,7 +276,6 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
|
||||||
lib/libuu.tex \
|
lib/libuu.tex \
|
||||||
lib/libsunaudio.tex \
|
lib/libsunaudio.tex \
|
||||||
lib/libfileinput.tex \
|
lib/libfileinput.tex \
|
||||||
lib/libxreadlines.tex \
|
|
||||||
lib/libimaplib.tex \
|
lib/libimaplib.tex \
|
||||||
lib/libpoplib.tex \
|
lib/libpoplib.tex \
|
||||||
lib/libcalendar.tex \
|
lib/libcalendar.tex \
|
||||||
|
|
|
||||||
|
|
@ -133,7 +133,6 @@ and how to embed it in other applications.
|
||||||
\input{libitertools}
|
\input{libitertools}
|
||||||
\input{libcfgparser}
|
\input{libcfgparser}
|
||||||
\input{libfileinput}
|
\input{libfileinput}
|
||||||
\input{libxreadlines}
|
|
||||||
\input{libcalendar}
|
\input{libcalendar}
|
||||||
\input{libcmd}
|
\input{libcmd}
|
||||||
\input{libshlex}
|
\input{libshlex}
|
||||||
|
|
@ -302,8 +301,6 @@ and how to embed it in other applications.
|
||||||
\input{libhmac}
|
\input{libhmac}
|
||||||
\input{libmd5}
|
\input{libmd5}
|
||||||
\input{libsha}
|
\input{libsha}
|
||||||
\input{libmpz}
|
|
||||||
\input{librotor}
|
|
||||||
|
|
||||||
\input{tkinter}
|
\input{tkinter}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,117 +0,0 @@
|
||||||
\section{\module{mpz} ---
|
|
||||||
GNU arbitrary magnitude integers}
|
|
||||||
|
|
||||||
\declaremodule{builtin}{mpz}
|
|
||||||
\modulesynopsis{Interface to the GNU MP library for arbitrary
|
|
||||||
precision arithmetic.}
|
|
||||||
|
|
||||||
|
|
||||||
\deprecated{2.2}{See the references at the end of this section for
|
|
||||||
information about packages which provide similar
|
|
||||||
functionality. This module will be removed in Python
|
|
||||||
2.3.}
|
|
||||||
|
|
||||||
|
|
||||||
This is an optional module. It is only available when Python is
|
|
||||||
configured to include it, which requires that the GNU MP software is
|
|
||||||
installed.
|
|
||||||
\index{MP, GNU library}
|
|
||||||
\index{arbitrary precision integers}
|
|
||||||
\index{integer!arbitrary precision}
|
|
||||||
|
|
||||||
This module implements the interface to part of the GNU MP library,
|
|
||||||
which defines arbitrary precision integer and rational number
|
|
||||||
arithmetic routines. Only the interfaces to the \emph{integer}
|
|
||||||
(\function{mpz_*()}) routines are provided. If not stated
|
|
||||||
otherwise, the description in the GNU MP documentation can be applied.
|
|
||||||
|
|
||||||
Support for rational numbers\index{rational numbers} can be
|
|
||||||
implemented in Python. For an example, see the
|
|
||||||
\module{Rat}\withsubitem{(demo module)}{\ttindex{Rat}} module, provided as
|
|
||||||
\file{Demos/classes/Rat.py} in the Python source distribution.
|
|
||||||
|
|
||||||
In general, \dfn{mpz}-numbers can be used just like other standard
|
|
||||||
Python numbers, e.g., you can use the built-in operators like \code{+},
|
|
||||||
\code{*}, etc., as well as the standard built-in functions like
|
|
||||||
\function{abs()}, \function{int()}, \ldots, \function{divmod()},
|
|
||||||
\function{pow()}. \strong{Please note:} the \emph{bitwise-xor}
|
|
||||||
operation has been implemented as a bunch of \emph{and}s,
|
|
||||||
\emph{invert}s and \emph{or}s, because the library lacks an
|
|
||||||
\cfunction{mpz_xor()} function, and I didn't need one.
|
|
||||||
|
|
||||||
You create an mpz-number by calling the function \function{mpz()} (see
|
|
||||||
below for an exact description). An mpz-number is printed like this:
|
|
||||||
\code{mpz(\var{value})}.
|
|
||||||
|
|
||||||
|
|
||||||
\begin{funcdesc}{mpz}{value}
|
|
||||||
Create a new mpz-number. \var{value} can be an integer, a long,
|
|
||||||
another mpz-number, or even a string. If it is a string, it is
|
|
||||||
interpreted as an array of radix-256 digits, least significant digit
|
|
||||||
first, resulting in a positive number. See also the \method{binary()}
|
|
||||||
method, described below.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{datadesc}{MPZType}
|
|
||||||
The type of the objects returned by \function{mpz()} and most other
|
|
||||||
functions in this module.
|
|
||||||
\end{datadesc}
|
|
||||||
|
|
||||||
|
|
||||||
A number of \emph{extra} functions are defined in this module. Non
|
|
||||||
mpz-arguments are converted to mpz-values first, and the functions
|
|
||||||
return mpz-numbers.
|
|
||||||
|
|
||||||
\begin{funcdesc}{powm}{base, exponent, modulus}
|
|
||||||
Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
|
|
||||||
\code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
|
|
||||||
\C{} library function, this version can handle negative exponents.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{funcdesc}{gcd}{op1, op2}
|
|
||||||
Return the greatest common divisor of \var{op1} and \var{op2}.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{funcdesc}{gcdext}{a, b}
|
|
||||||
Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
|
|
||||||
\code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{funcdesc}{sqrt}{op}
|
|
||||||
Return the square root of \var{op}. The result is rounded towards zero.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{funcdesc}{sqrtrem}{op}
|
|
||||||
Return a tuple \code{(\var{root}, \var{remainder})}, such that
|
|
||||||
\code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
\begin{funcdesc}{divm}{numerator, denominator, modulus}
|
|
||||||
Returns a number \var{q} such that
|
|
||||||
\code{\var{q} * \var{denominator} \%{} \var{modulus} ==
|
|
||||||
\var{numerator}}. One could also implement this function in Python,
|
|
||||||
using \function{gcdext()}.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
An mpz-number has one method:
|
|
||||||
|
|
||||||
\begin{methoddesc}[mpz]{binary}{}
|
|
||||||
Convert this mpz-number to a binary string, where the number has been
|
|
||||||
stored as an array of radix-256 digits, least significant digit first.
|
|
||||||
|
|
||||||
The mpz-number must have a value greater than or equal to zero,
|
|
||||||
otherwise \exception{ValueError} will be raised.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
|
|
||||||
\begin{seealso}
|
|
||||||
\seetitle[http://gmpy.sourceforge.net/]{General Multiprecision Python}{
|
|
||||||
This project is building new numeric types to allow
|
|
||||||
arbitrary-precision arithmetic in Python. Their first
|
|
||||||
efforts are also based on the GNU MP library.}
|
|
||||||
|
|
||||||
\seetitle[http://www.egenix.com/files/python/mxNumber.html]{mxNumber
|
|
||||||
--- Extended Numeric Types for Python}{Another wrapper
|
|
||||||
around the GNU MP library, including a port of that
|
|
||||||
library to Windows.}
|
|
||||||
\end{seealso}
|
|
||||||
|
|
@ -1,110 +0,0 @@
|
||||||
\section{\module{rotor} ---
|
|
||||||
Enigma-like encryption and decryption}
|
|
||||||
|
|
||||||
\declaremodule{builtin}{rotor}
|
|
||||||
\modulesynopsis{Enigma-like encryption and decryption.}
|
|
||||||
|
|
||||||
\deprecated{2.3}{The encryption algorithm is insecure.}
|
|
||||||
|
|
||||||
|
|
||||||
This module implements a rotor-based encryption algorithm, contributed by
|
|
||||||
Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived
|
|
||||||
from the Enigma device\indexii{Enigma}{device}, a machine
|
|
||||||
used during World War II to encipher messages. A rotor is simply a
|
|
||||||
permutation. For example, if the character `A' is the origin of the rotor,
|
|
||||||
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
|
|
||||||
To encrypt, we choose several different rotors, and set the origins of the
|
|
||||||
rotors to known positions; their initial position is the ciphering key. To
|
|
||||||
encipher a character, we permute the original character by the first rotor,
|
|
||||||
and then apply the second rotor's permutation to the result. We continue
|
|
||||||
until we've applied all the rotors; the resulting character is our
|
|
||||||
ciphertext. We then change the origin of the final rotor by one position,
|
|
||||||
from `A' to `B'; if the final rotor has made a complete revolution, then we
|
|
||||||
rotate the next-to-last rotor by one position, and apply the same procedure
|
|
||||||
recursively. In other words, after enciphering one character, we advance
|
|
||||||
the rotors in the same fashion as a car's odometer. Decoding works in the
|
|
||||||
same way, except we reverse the permutations and apply them in the opposite
|
|
||||||
order.
|
|
||||||
\indexii{Enigma}{cipher}
|
|
||||||
|
|
||||||
The available functions in this module are:
|
|
||||||
|
|
||||||
\begin{funcdesc}{newrotor}{key\optional{, numrotors}}
|
|
||||||
Return a rotor object. \var{key} is a string containing the encryption key
|
|
||||||
for the object; it can contain arbitrary binary data but not null bytes.
|
|
||||||
The key will be used
|
|
||||||
to randomly generate the rotor permutations and their initial positions.
|
|
||||||
\var{numrotors} is the number of rotor permutations in the returned object;
|
|
||||||
if it is omitted, a default value of 6 will be used.
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
Rotor objects have the following methods:
|
|
||||||
|
|
||||||
\begin{methoddesc}[rotor]{setkey}{key}
|
|
||||||
Sets the rotor's key to \var{key}. The key should not contain null bytes.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
\begin{methoddesc}[rotor]{encrypt}{plaintext}
|
|
||||||
Reset the rotor object to its initial state and encrypt \var{plaintext},
|
|
||||||
returning a string containing the ciphertext. The ciphertext is always the
|
|
||||||
same length as the original plaintext.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
\begin{methoddesc}[rotor]{encryptmore}{plaintext}
|
|
||||||
Encrypt \var{plaintext} without resetting the rotor object, and return a
|
|
||||||
string containing the ciphertext.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
\begin{methoddesc}[rotor]{decrypt}{ciphertext}
|
|
||||||
Reset the rotor object to its initial state and decrypt \var{ciphertext},
|
|
||||||
returning a string containing the plaintext. The plaintext string will
|
|
||||||
always be the same length as the ciphertext.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
\begin{methoddesc}[rotor]{decryptmore}{ciphertext}
|
|
||||||
Decrypt \var{ciphertext} without resetting the rotor object, and return a
|
|
||||||
string containing the plaintext.
|
|
||||||
\end{methoddesc}
|
|
||||||
|
|
||||||
An example usage:
|
|
||||||
\begin{verbatim}
|
|
||||||
>>> import rotor
|
|
||||||
>>> rt = rotor.newrotor('key', 12)
|
|
||||||
>>> rt.encrypt('bar')
|
|
||||||
'\xab4\xf3'
|
|
||||||
>>> rt.encryptmore('bar')
|
|
||||||
'\xef\xfd$'
|
|
||||||
>>> rt.encrypt('bar')
|
|
||||||
'\xab4\xf3'
|
|
||||||
>>> rt.decrypt('\xab4\xf3')
|
|
||||||
'bar'
|
|
||||||
>>> rt.decryptmore('\xef\xfd$')
|
|
||||||
'bar'
|
|
||||||
>>> rt.decrypt('\xef\xfd$')
|
|
||||||
'l(\xcd'
|
|
||||||
>>> del rt
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
The module's code is not an exact simulation of the original Enigma
|
|
||||||
device; it implements the rotor encryption scheme differently from the
|
|
||||||
original. The most important difference is that in the original
|
|
||||||
Enigma, there were only 5 or 6 different rotors in existence, and they
|
|
||||||
were applied twice to each character; the cipher key was the order in
|
|
||||||
which they were placed in the machine. The Python \module{rotor}
|
|
||||||
module uses the supplied key to initialize a random number generator;
|
|
||||||
the rotor permutations and their initial positions are then randomly
|
|
||||||
generated. The original device only enciphered the letters of the
|
|
||||||
alphabet, while this module can handle any 8-bit binary data; it also
|
|
||||||
produces binary output. This module can also operate with an
|
|
||||||
arbitrary number of rotors.
|
|
||||||
|
|
||||||
The original Enigma cipher was broken in 1944. % XXX: Is this right?
|
|
||||||
The version implemented here is probably a good deal more difficult to crack
|
|
||||||
(especially if you use many rotors), but it won't be impossible for
|
|
||||||
a truly skillful and determined attacker to break the cipher. So if you want
|
|
||||||
to keep the NSA out of your files, this rotor cipher may well be unsafe, but
|
|
||||||
for discouraging casual snooping through your files, it will probably be
|
|
||||||
just fine, and may be somewhat safer than using the \UNIX{} \program{crypt}
|
|
||||||
command.
|
|
||||||
\index{NSA}
|
|
||||||
\index{National Security Agency}
|
|
||||||
|
|
@ -1,58 +0,0 @@
|
||||||
\section{\module{xreadlines} ---
|
|
||||||
Efficient iteration over a file}
|
|
||||||
|
|
||||||
\declaremodule{extension}{xreadlines}
|
|
||||||
\modulesynopsis{Efficient iteration over the lines of a file.}
|
|
||||||
|
|
||||||
\versionadded{2.1}
|
|
||||||
|
|
||||||
\deprecated{2.3}{Use \samp{for \var{line} in \var{file}} instead.}
|
|
||||||
|
|
||||||
This module defines a new object type which can efficiently iterate
|
|
||||||
over the lines of a file. An xreadlines object is a sequence type
|
|
||||||
which implements simple in-order indexing beginning at \code{0}, as
|
|
||||||
required by \keyword{for} statement or the
|
|
||||||
\function{filter()} function.
|
|
||||||
|
|
||||||
Thus, the code
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
import xreadlines, sys
|
|
||||||
|
|
||||||
for line in xreadlines.xreadlines(sys.stdin):
|
|
||||||
pass
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
has approximately the same speed and memory consumption as
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
while 1:
|
|
||||||
lines = sys.stdin.readlines(8*1024)
|
|
||||||
if not lines: break
|
|
||||||
for line in lines:
|
|
||||||
pass
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
except the clarity of the \keyword{for} statement is retained in the
|
|
||||||
former case.
|
|
||||||
|
|
||||||
\begin{funcdesc}{xreadlines}{fileobj}
|
|
||||||
Return a new xreadlines object which will iterate over the contents
|
|
||||||
of \var{fileobj}. \var{fileobj} must have a \method{readlines()}
|
|
||||||
method that supports the \var{sizehint} parameter. \note{Because
|
|
||||||
the \method{readlines()} method buffers data, this effectively
|
|
||||||
ignores the effects of setting the file object as unbuffered.}
|
|
||||||
\end{funcdesc}
|
|
||||||
|
|
||||||
An xreadlines object \var{s} supports the following sequence
|
|
||||||
operation:
|
|
||||||
|
|
||||||
\begin{tableii}{c|l}{code}{Operation}{Result}
|
|
||||||
\lineii{\var{s}[\var{i}]}{\var{i}'th line of \var{s}}
|
|
||||||
\end{tableii}
|
|
||||||
|
|
||||||
If successive values of \var{i} are not sequential starting from
|
|
||||||
\code{0}, this code will raise \exception{RuntimeError}.
|
|
||||||
|
|
||||||
After the last line of the file is read, this code will raise an
|
|
||||||
\exception{IndexError}.
|
|
||||||
Loading…
Reference in New Issue