search

rafaels88 / py2docx

A python module to create DOCX documents
MIT License
16 stars 7 forks source link

readme

Py2Docx - 0.2.0v

Release Date: June 18, 2014

Py2Docx is a python module to write .docx documents (>= Microsoft Word 2007).

Last Modifications

Instalation

$ pip install py2docx

Example

# coding: utf-8
from py2docx.docx import Docx
from py2docx.elements import Block
from py2docx.elements.text import InlineText, Break, BlockText
from py2docx.elements.image import Image
from py2docx.elements.table import Table, Cell

doc = Docx()
t1 = InlineText("An Inline Text", bold=True, italic=True,
                underline={'style': 'solid', 'color': '#4433ff'},
                color="#FF0000")

bl = Block()
bl.append(t1)

bl2 = Block(align='center')
bl2.append(t1)

t = Table(width="100%", padding='5pt', border={'left': {'style': 'dashed'}})
c1 = Cell()
c1.append(bl)
c2 = Cell([bl])
c3 = Cell(bl2, valign='top', border={'left': {'size': '1pt', 'color': '#33ddff'}})

t.add_row([c1, c2])
t.add_row([c1, c3])

bl3 = Block([InlineText("Inline Text "),
             InlineText("Bold Here", bold=True)])

i = Image("Pictures/into_the_wild.jpg", document=doc,
          align='center', width='50%', height='50%')

doc.append(bl)
doc.append(t)
doc.append(Block(Break()))
doc.append(i)
doc.append(BlockText("This is a Block Text"))
doc.append(Block(InlineText("This is a Block Text")))
doc.append(bl3)
doc.append(BlockText(u"Arial Test", font='Arial', size=20))

doc.save("./py2docx.docx")

API

Creating a Document

Docx

from py2docx.docx import Docx

Create a document

Methods:
append(elem)
Parameter Description
elem An Image, Block or Table to put in the document. 
doc = Docx()
bl = Block()
doc.append(bl)
save(path)
Parameter Description
path The path that the document are going to be saved. 
doc = Docx()
doc.save("./example.docx")

Elements

Block

from py2docx.docx.elements import Block

Block elements is almost the same like "\<div>" HTML element.

Methods:
init(initial=None, align=None)
Parameter Description
initial One element or a list of elements to put inside the block.
align Horizontal align. Options are: 'left', 'right', 'center' or 'justify'. 
text = InlineText("Hello World!")
block = Block(text, align='center')
append(elem)
text = InlineText("Hello World!")
block = Block()
block.append(text)
Parameter Description
elem Any element to put inside the block.

Image

from py2docx.elements.image import Image
Methods:
init(path, document, align=None, width='100%', height='100%')

The accepted types are: png, jpg, gif, jpeg.

Parameters Description
path A string with the image's path.
document The instance of the document (Docx())
align Horizontal Align. Values should be: 'left', 'center' or 'right'
width Width in percentage (string format: '90%').
height Heigth in percentage (string format: '50%'). 
doc = Docx()
Image("/Pictures/image.png", document=doc,
      align='right', width='80%', heigth='40%')

Table

from py2docx.elements.table import Table
Methods:
init(padding=None, width=None, border=None)
Parameters Description
padding Padding for all cells. Should be in one of these units: cm (centimeters), in (inches) or pt (points). The numbers should be in the W3C CSS Format.
width Width of the table. Should be in one of these units: % (percentage), cm (centimeters), in (inches) or pt (points).
border A dict with the specifications. Should be in this format: {'[SIDE]': {'color': '#[HEX]', 'size': '[INT]pt', 'style': '[dotted,dashed,solid,double]'}. The maximum size of the border is 12pt, minimum is 0.5pt. 
Table(width='100%', padding='2cm', border={'left': {'color': '#FF0000', 'size': '2pt', 'style': 'dotted'},
                                           'bottom': {'color': '#FF0000', 'size': '2pt',' style': 'dashed'},
                                           'top': {'color': '#FFFFFF', 'size': '3pt', 'style': 'solid'},
                                           'right': {'color': '#000000', 'size': '3pt', 'style': 'double'}})
add_row(cells)
Parameters Description
cells A list of Cells to put on a row. 
t = Table(width='100%')
t.add_row([Cell(), Cell()])

Cell

from py2docx.elements.table import Cell
Methods:
init(initial=None, bgcolor=None, padding=None, width=None, valign=None, nowrap=None, border=None, colspan=1)
Parameters Description
initial One element or a list of elements to put inside the cell.
bgcolor Background color of the cell, in hexadecimal '#00FF66'.
padding Padding for cell. Should be in one of these units: cm (centimeters), in (inches) or pt (points). The numbers should be in the W3C CSS Format.
width Width of the cell. Should be in one of these units: % (percentage), cm (centimeters), in (inches) or pt (points).
valign Vertical Align. Options are: 'top', 'center', 'bottom'.
nowrap True or False. It does not work with width.
border A dict with the specifications. Should be in this format: {'[SIDE]': {'color': '#[HEX]', 'size': '[INT]pt', 'style': '[dotted,dashed,solid,double]'}. The maximum size of the border is 12pt, minimum is 0.5pt.
colspan An int with the number of cells. 
Cell([Image("path/filename.ext"), BlockText("Hello World!")], bgcolor='#3377FF', padding='5cm 10cm',
     width='5cm', valign='center', border={'bottom': {'color': '#FF0000', 'size': '2pt', 'style': 'dashed'}, colspan=2)
append(elem)
text = InlineText("Hello World!")
c = Cell()
c.append(text)
Parameter Description
elem A Cell, Block, BlockText or Image, to put inside the cell.

InlineText

from py2docx.elements.text import InlineText

You should put this in a Block. This is like a "\<span>" HTML element.

Methods:
init(text, bold=None, italic=None, underline=None, uppercase=None, color=None, font=None, size=None)
Parameters Description
text A string with words.
bold True or False.
italic True or False.
underline A dict with properties: {'style': '[dotted/dashed/solid/double]', 'color': '#[HEX]'}.
uppercase True or False.
color Hexadecimal color.
font Should be 'Cambria', 'Times New Roman', 'Arial' or 'Calibri'.
size An INT of font's size in point. 
InlineText("Hello World!", bold=True, italic=True,
                underline={'style': 'solid', 'color': '#4433ff'},
                uppercase=True, color="#FF0000", font="Times New Roman",
                size=14)

Break

from py2docx.elements.text import Break

The same as "\<br\ >" HTML element.

hello = InlineText("Hello")
world = InlineText("World", bold=True)

Block([hello, Break(), world])

BlockText

from py2docx.elements.text import BlockText

The same thing as:

Block(InlineText("Hello World"))
Methods:
init(text, bold=None, italic=None, underline=None, uppercase=None, color=None, font=None, size=None)
Parameters Description
text A string with words.
bold True or False.
italic True or False.
underline A dict with properties: {'style': '[dotted/dashed/solid/double]', 'color': '#[HEX]'}.
uppercase True or False.
color Hexadecimal color.
font Should be 'Cambria', 'Times New Roman', 'Arial' or 'Calibri'.
size An INT of font's size in point. 
BlockText("Hello World!", bold=True, italic=True,
          underline={'style': 'solid', 'color': '#4433ff'},
          uppercase=True, color="#FF0000", font="Times New Roman",
          size=14)