rdkit.sping.PDF.pdfgen module

PDFgen is a library to generate PDF files containing text and graphics. It is the foundation for a complete reporting solution in Python. It is also the foundation for piddlePDF, the PDF back end for PIDDLE.

Documentation is a little slim right now; run then look at testpdfgen.py to get a clue.

———- Licence Terms (same as the Python license) —————– (C) Copyright Robinson Analytics 1998-1999.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Robinson Analytics not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

ROBINSON ANALYTICS LTD. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL ROBINSON ANALYTICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Progress Reports: 0.82, 1999-10-27, AR:

Fixed some bugs on printing to Postscript. Added ‘Text Object’ analogous to Path Object to control entry and exit from text mode. Much simpler clipping API. All verified to export Postscript and redistill. One limitation still - clipping to text paths is fine in Acrobat but not in Postscript (any level)

0.81,1999-10-13, AR:

Adding RoundRect; changed all format strings to use %0.2f instead of %s, so we don’t get exponentials in the output.

0.8,1999-10-07, AR: all changed!

2000-02-07: changed all %0.2f’s to %0.4f in order to allow precise ploting of graphs that

range between 0 and 1 -cwl

class rdkit.sping.PDF.pdfgen.Canvas(filename, pagesize=(595.27, 841.89), bottomup=1)

Bases: object

This is a low-level interface to the PDF file format. The plan is to expose the whole pdfgen API through this. Its drawing functions should have a one-to-one correspondence with PDF functionality. Unlike PIDDLE, it thinks in terms of RGB values, Postscript font names, paths, and a ‘current graphics state’. Just started development at 5/9/99, not in use yet.

addLiteral(s, escaped=1)

arc(x1, y1, x2, y2, startAng=0, extent=90)

Contributed to piddlePDF by Robert Kern, 28/7/99. Trimmed down by AR to remove color stuff for pdfgen.canvas and revert to positive coordinates.

Draw a partial ellipse inscribed within the rectangle x1,y1,x2,y2, starting at startAng degrees and covering extent degrees. Angles start with 0 to the right (+x) and increase counter-clockwise. These should have x1<x2 and y1<y2.

The algorithm is an elliptical generalization of the formulae in Jim Fitzsimmon’s TeX tutorial <URL: http://www.tinaja.com/bezarc1.pdf>.

beginPath()

Returns a fresh path object

beginText(x=0, y=0)

Returns a fresh text object

bezier(x1, y1, x2, y2, x3, y3, x4, y4)

Bezier curve with the four given control points

circle(x_cen, y_cen, r, stroke=1, fill=0)

special case of ellipse

clipPath(aPath, stroke=1, fill=0)

clip as well as drawing

drawCentredString(x, y, text)

Draws a string right-aligned with the y coordinate. I am British so the spelling is correct, OK?

drawInlineImage(image, x, y, width=None, height=None)

Draw a PIL Image into the specified rectangle. If width and height are omitted, they are calculated from the image size. Also allow file names as well as images. This allows a caching mechanism

drawPath(aPath, stroke=1, fill=0)

Draw in the mode indicated

drawRightString(x, y, text)

Draws a string right-aligned with the y coordinate

drawString(x, y, text)

Draws a string in the current text styles.

drawText(aTextObject)

Draws a text object

ellipse(x1, y1, x2, y2, stroke=1, fill=0)

Uses bezierArc, which conveniently handles 360 degrees - nice touch Robert

getAvailableFonts()

Returns the list of PostScript font names available. Standard set now, but may grow in future with font embedding.

getPageNumber()

grid(xlist, ylist)

Lays out a grid in current line style. Suuply list of x an y positions.

line(x1, y1, x2, y2)

As it says

lines(linelist)

As line(), but slightly more efficient for lots of them - one stroke operation and one less function call

pageHasData()

Info function - app can call it after showPage to see if it needs a save

readJPEGInfo(image)

Read width, height and number of components from JPEG file

rect(x, y, width, height, stroke=1, fill=0)

draws a rectangle

restoreState()

These need expanding to save/restore Python’s state tracking too

rotate(theta)

theta is in degrees.

roundRect(x, y, width, height, radius, stroke=1, fill=0)

Draws a rectangle with rounded corners. The corners are approximately quadrants of a circle, with the given radius.

save(filename=None, fileobj=None)

Saves the pdf document to fileobj or to file with name filename. If holding data, do a showPage() to save them having to.

saveState()

These need expanding to save/restore Python’s state tracking too

scale(x, y)

setAuthor(author)

setDash(array=[], phase=0)

Two notations. pass two numbers, or an array and phase

setFillColorRGB(r, g, b)

setFont(psfontname, size, leading=None)

Sets the font. If leading not specified, defaults to 1.2 x font size. Raises a readable exception if an illegal font is supplied. Font names are case-sensitive! Keeps track of font anme and size for metrics.

setLineCap(mode)

0=butt,1=round,2=square

setLineJoin(mode)

0=mitre, 1=round, 2=bevel

setLineWidth(width)

setMiterLimit(limit)

setPageCompression(onoff=1)

Possible values 1 or 0 (1 for ‘on’ is the default). If on, the page data will be compressed, leading to much smaller files, but takes a little longer to create the files. This applies to all subsequent pages, or until setPageCompression() is next called.

setPageSize(size)

accepts a 2-tuple in points for paper size for this and subsequent pages

setPageTransition(effectname=None, duration=1, direction=0, dimension='H', motion='I')

PDF allows page transition effects for use when giving presentations. There are six possible effects. You can just guive the effect name, or supply more advanced options to refine the way it works. There are three types of extra argument permitted, and here are the allowed values:

direction_arg = [0,90,180,270] dimension_arg = [‘H’, ‘V’] motion_arg = [‘I’,’O’] (start at inside or outside)

This table says which ones take which arguments:

PageTransitionEffects = {

‘Split’: [direction_arg, motion_arg], ‘Blinds’: [dimension_arg], ‘Box’: [motion_arg], ‘Wipe’ : [direction_arg], ‘Dissolve’ : [], ‘Glitter’:[direction_arg] }

Have fun!

setStrokeColorRGB(r, g, b)

setSubject(subject)

setTitle(title)

showPage()

This is where the fun happens

skew(alpha, beta)

stringWidth(text, fontname, fontsize)

gets width of a string in the given font and size

transform(a, b, c, d, e, f)

How can Python track this?

translate(dx, dy)

wedge(x1, y1, x2, y2, startAng, extent, stroke=1, fill=0)

Like arc, but connects to the centre of the ellipse. Most useful for pie charts and PacMan!

exception rdkit.sping.PDF.pdfgen.PDFError

Bases: ValueError

class rdkit.sping.PDF.pdfgen.PDFPathObject

Bases: object

Represents a graphic path. There are certain ‘modes’ to PDF drawing, and making a separate object to expose Path operations ensures they are completed with no run-time overhead. Ask the Canvas for a PDFPath with getNewPathObject(); moveto/lineto/ curveto wherever you want; add whole shapes; and then add it back into the canvas with one of the relevant operators.

Path objects are probably not long, so we pack onto one line

arc(x1, y1, x2, y2, startAng=0, extent=90)

Contributed to piddlePDF by Robert Kern, 28/7/99. Draw a partial ellipse inscribed within the rectangle x1,y1,x2,y2, starting at startAng degrees and covering extent degrees. Angles start with 0 to the right (+x) and increase counter-clockwise. These should have x1<x2 and y1<y2.

The algorithm is an elliptical generalization of the formulae in Jim Fitzsimmon’s TeX tutorial <URL: http://www.tinaja.com/bezarc1.pdf>.

arcTo(x1, y1, x2, y2, startAng=0, extent=90)

Like arc, but draws a line from the current point to the start if the start is not the current point.

circle(x_cen, y_cen, r)

adds a circle to the path

close()

draws a line back to where it started

curveTo(x1, y1, x2, y2, x3, y3)

ellipse(x, y, width, height)

adds an ellipse to the path

getCode()

pack onto one line; used internally

lineTo(x, y)

moveTo(x, y)

rect(x, y, width, height)

Adds a rectangle to the path

class rdkit.sping.PDF.pdfgen.PDFTextObject(canvas, x=0, y=0)

Bases: object

PDF logically separates text and graphics drawing; you can change the coordinate systems for text and graphics independently. If you do drawings while in text mode, they appear in the right places on the page in Acrobat Reader, bur when you export Postscript to a printer the graphics appear relative to the text coordinate system. I regard this as a bug in how Acrobat exports to PostScript, but this is the workaround. It forces the user to separate text and graphics. To output text, ask te canvas for a text object with beginText(x, y). Do not construct one directly. It keeps track of x and y coordinates relative to its origin.

getCode()

pack onto one line; used internally

getCursor()

Returns current text position relative to the last origin.

getX()

Returns current x position relative to the last origin.

getY()

Returns current y position relative to the last origin.

moveCursor(dx, dy)

Moves to a point dx, dy away from the start of the current line - NOT from the current point! So if you call it in mid-sentence, watch out.

setCharSpace(charSpace)

Adjusts inter-character spacing

setFillColorRGB(r, g, b)

setFont(psfontname, size, leading=None)

Sets the font. If leading not specified, defaults to 1.2 x font size. Raises a readable exception if an illegal font is supplied. Font names are case-sensitive! Keeps track of font anme and size for metrics.

setHorizScale(horizScale)

Stretches text out horizontally

setLeading(leading)

How far to move down at the end of a line.

setRise(rise)

Move text baseline up or down to allow superscrip/subscripts

setStrokeColorRGB(r, g, b)

setTextOrigin(x, y)

setTextRenderMode(mode)

Set the text rendering mode.

0 = Fill text 1 = Stroke text 2 = Fill then stroke 3 = Invisible 4 = Fill text and add to clipping path 5 = Stroke text and add to clipping path 6 = Fill then stroke and add to clipping path 7 = Add to clipping path

setTextTransform(a, b, c, d, e, f)

Like setTextOrigin, but does rotation, scaling etc.

setWordSpace(wordSpace)

Adjust inter-word spacing. This can be used to flush-justify text - you get the width of the words, and add some space between them.

textLine(text='')

prints string at current point, text cursor moves down. Can work with no argument to simply move the cursor down.

textLines(stuff, trim=1)

prints multi-line or newlined strings, moving down. One comon use is to quote a multi-line block in your Python code; since this may be indented, by default it trims whitespace off each line and from the beginning; set trim=0 to preserve whitespace.

textOut(text)

prints string at current point, text cursor moves across