languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-07-21 10:15:53 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Remove docs for xreadlines, mpz, rotor

Browse source
This commit is contained in:
Andrew M. Kuchling 2004-08-31 13:22:43 +00:00
parent e723863ba1
commit ab459f71d6
5 changed files with 0 additions and 291 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
Doc/Makefile.deps
View file

@ -203,9 +203,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
lib/libcrypto.tex \
lib/libmd5.tex \
lib/libsha.tex \
lib/libmpz.tex \
lib/libhmac.tex \
lib/librotor.tex \
lib/libstdwin.tex \
lib/libsgi.tex \
lib/libal.tex \
@ -278,7 +276,6 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
lib/libuu.tex \
lib/libsunaudio.tex \
lib/libfileinput.tex \
lib/libxreadlines.tex \
lib/libimaplib.tex \
lib/libpoplib.tex \
lib/libcalendar.tex \

3
Doc/lib/lib.tex
View file

@ -133,7 +133,6 @@ and how to embed it in other applications.
\input{libitertools}
\input{libcfgparser}
\input{libfileinput}
\input{libxreadlines}
\input{libcalendar}
\input{libcmd}
\input{libshlex}
@ -302,8 +301,6 @@ and how to embed it in other applications.
\input{libhmac}
\input{libmd5}
\input{libsha}
\input{libmpz}
\input{librotor}
\input{tkinter}

117
Doc/lib/libmpz.tex
View file

@ -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}

110
Doc/lib/librotor.tex
View file

@ -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}

58
Doc/lib/libxreadlines.tex
View file

@ -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}.