Overview¶

Option 1. Get the latest official version¶

1. Get the latest tarball available at:

   http://pypi.python.org/pypi/Geraldo/

2. Then you can do the following steps to install it:

Linux

tar xvfz Geraldo-latest.tar.gz
cd Geraldo
sudo python setup.py install

This will copy Geraldo’s packages inside Python’s packages path.

Windows

If you are using Windows, Geraldo is fully compatible. You just have to use a tarball decompression tool, like 7-Zip which you can download from:

http://www.7-zip.org/download.html

Once you have a tool to decompress tarball files, you have to decompress it, open a DOS Prompt window in the folder you decompress into and run the following command:

python setup.py install

Option 2. Get the latest development version¶

Our version control is centralized on GitHub Social repository, in the following URL:

http://github.com/marinho/geraldo

To get the latest development version from repository server, you will need the Git version control system. Then you can run the following command in Shell or MS-DOS Prompty window:

git clone git://github.com/marinho/geraldo.git

A folder named geraldo will be in your current path with all Geraldo files inside.

Then you can go ahead and use the same commands from Option 1 to install in your system.

Dependencies¶

ReportLab

This is required, as you cannot use Geraldo without ReportLab installed.

Get it from the following URL:

http://www.reportlab.org/

The tested version is 2.1.

Python Imaging Library

Geraldo depends on PIL to work with Images manipulation on the canvas. If you aren’t going to use them, you can live without PIL.

To get PIL you can go to the following URL:

http://www.pythonware.com/products/pil/

pyPDF library

Optional. We use it to concatenate many PDF files when you enable partial generation or merging reports.

Step 1. Preparing your project¶

To install Geraldo in your Django project, you must change the setting INSTALLED_APPS in your settings.py file and this should be enough.

But let’s create a new URL to load a PDF report online.

Attention: Geraldo can work with online or file ways to get a PDF. You are not dependent on a URL or view to generate reports from Geraldo. This is just one of many ways you can do it.

We are going to work with a common example for this kind of solution: a purchasing application.

Let’s say you have the following model classes:

class Product(models.Model):
    name = models.CharField(max_length=100)

class Customer(models.Model):
    name = models.CharField(max_length=100)

class Purchase(models.Model):
    customer = models.ForeignKey('Customer')
    delivery_address = models.CharField(max_length=70, blank=True)
    date_creation = models.DateField(blank=True, default=date.today())
    date_bill = models.DateField(blank=True, null=True)
    date_delivery = models.DateField(blank=True, null=True)
    taxes = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)
    sub_total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)
    total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)

class PurchaseItem(models.Model):
    purchase = models.ForeignKey('Purchase')
    product = models.ForeignKey('Product')
    unit_price = models.DecimalField(max_digits=12, decimal_places=2)
    quantity = models.DecimalField(max_digits=12, decimal_places=2)
    total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)

First you declare a new URL, for example:

urlpatterns = patterns('purchases.views',
    url('^purchase-report/$', 'purchase_report'),
)

The next step is you have a view for the created URL, like this:

from django.http import HttpResponse

from reports import ReportPurchase
from geraldo.generators import PDFGenerator
from models import Purchase

def purchase_report(request):
    resp = HttpResponse(mimetype='application/pdf')

    purchases = Purchase.objects.order_by('customer', 'id')
    report = ReportPurchase(queryset=purchases)
    report.generate_by(PDFGenerator, filename=resp)

    return resp

You can see you first imported two important things:

from reports import ReportPurchase
from geraldo.generators import PDFGenerator

Your report class (we will create it in the next step) and the generator class PDFGenerator you will need to generate a PDF file. In the future we will have other generators, for other formats of file.

The next thing to note is that you are going to return a PDF format HttpResponse:

resp = HttpResponse(mimetype='application/pdf')

Now you are going to work your report instance:

purchases = Purchase.objects.order_by('customer', 'id')
report = ReportPurchase(queryset=purchases)
report.generate_by(PDFGenerator, filename=resp)

• The first thing you did is to get all purchases, ordered by ‘customer’ and ‘id’ fields;
• Afterwards, you got a report instance from your report class ReportPurchase, using purchases queryset as report driver queryset;
• And last, you called the ‘generate_by’ method of the generator class.

Now you have a prepared Django application to use a report you are going to create at the next step!

Declaring the report class¶

The report class must be an inheritance from geraldo.Report class. You can create a new file ‘reports.py’ to declare your report classes inside.

from geraldo import Report

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

To see something more complex, you can set the page size, margins and other report attributes, like below:

from geraldo import Report, landscape
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

As you can see, we use what we can from the ReportLab libraries, their units, page sizes, stylizing, etc.

A report is driven by bands. If you are used to working with other report engines you know what a band is.

A band is a row with elements in the report canvas. Bands in essence are the same but their use varies depending whether you are using a band as the Page Header or Report Summary, for example.

A report can have a band for each one of following attributes:

Detail band¶

The detail band is the most important band in a report. This is because the detail band is the reason of the existence of every report.

The detail band is used most of the time to show object field values. This is the same for a detailed info page or just a simple list or grid.

The detail band is rendered one time for each object in the queryset attribute. So, if you have 10 objects in the queryset, you will have the detail band rendered 10 times.

Let’s change our report to have a detail band, see below:

from geraldo import Report, landscape, ReportBand, ObjectValue
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

    class band_detail(ReportBand):
        height = 0.5*cm
        elements=(
            ObjectValue(attribute_name='id', left=0.5*cm),
            ObjectValue(attribute_name='date_creation', left=3*cm,
                get_value=lambda instance: instance.date_creation.strftime('%m/%d/%Y')),
            )

The attribute band_detail is locally declared as a class, but it could alternatively be set with an external class.

The important thing here is that the band has the attribute height, fixed with a defined height in centimeters.

The second thing to observe is the elements list, with 2 widgets representing 2 model class fields: id and date_creation. The last one is customized with the get_value attribute, for date field formatting.

Page Header and Page Footer bands¶

Page header and Page footer bands are designed to appear on the header and footer, respectively, on every page in the report.

In most reports, a page header is used to show the report title and its page number, page count and maybe the columns header if you are creating a list or grid report.

In the same way, a page footer band is used to show footer information, like the print date/time, software name, company’s mark, etc.

Add this code block to the end of the report class to have both bands:

class band_page_header(ReportBand):
    height = 1.3*cm
    elements = [
            SystemField(expression='%(report_title)s', top=0.1*cm, left=0, width=BAND_WIDTH,
                style={'fontName': 'Helvetica-Bold', 'fontSize': 14, 'alignment': TA_CENTER}),
            Label(text="ID", top=0.8*cm, left=0.5*cm),
            Label(text=u"Creation Date", top=0.8*cm, left=3*cm),
            SystemField(expression=u'Page %(page_number)d of %(page_count)d', top=0.1*cm,
                width=BAND_WIDTH, style={'alignment': TA_RIGHT}),
            ]
    borders = {'bottom': True}

class band_page_footer(ReportBand):
    height = 0.5*cm
    elements = [
            Label(text='Geraldo Reports', top=0.1*cm),
            SystemField(expression=u'Printed in %(now:%Y, %b %d)s at %(now:%H:%M)s', top=0.1*cm,
                width=BAND_WIDTH, style={'alignment': TA_RIGHT}),
            ]
    borders = {'top': True}

Now you have to change the top lines of the file with imports to import some new elements:

from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
        BAND_WIDTH, Label

from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm
from reportlab.lib.enums import TA_RIGHT, TA_CENTER

The new elements for you now are:

• SystemField - shows a system field, like current date/time, page number, page count, report title, report author, etc.
• Label - show a free text
• BAND_WIDTH - sets the width automatically to its parent band width;
• TA_RIGHT and TA_CENTER - they set the alignment of a widget

Other good use of Page Header and Page Footer bands is to compose or inherit reports layout. Use your imagination!

Grouping¶

The next thing now is to group our purchases by a field. Let’s choose the field customer, ok?

Geraldo allows you to group a report at many levels. This means you can group the report objects by 1, 2 or however many fields you want and have a header and footer to show their aggregation information and other features.

But for now, just add the following code to the end of reports.py:

groups = [
        ReportGroup(attribute_name = 'customer',
            band_header = ReportBand(
                height = 0.7*cm,
                elements = [
                    ObjectValue(attribute_name='customer', left=0, top=0.1*cm, width=20*cm,
                        get_value=lambda instance: 'Customer: ' + (instance.customer.name),
                        style={'fontName': 'Helvetica-Bold', 'fontSize': 12})
                    ],
                borders = {'bottom': True},
                )
            ),
        ]

In the same way as you did before, you have to change the top imports to have the new elements:

from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
        BAND_WIDTH, Label, ReportGroup

The two important things now are:

• attribute_name - this attribute in ReportGroup defines which field we are going to use to group the objects. You must order the queryset beforehand by this attribute to have it working properly. Here you can use a field name, free attribute, property or method that you have in queryset objects;
• band_header - this band is for you to show things above the group. You can also use band_footer if you wish.

SubReports¶

SubReport is the way you have to show object children data in a report. As you know, a purchase has many items, and they are available in attribute purchase.purchaseitem_set.all() os something like that.

Geraldo allows you to have however many subreports you want, and they will appear in the same sequence that you place them in the class declaration.

Just add the following block of code to the end of reports.py:

subreports = [
        SubReport(
            queryset_string = '%(object)s.purchaseitem_set.all()',
            detail_band = ReportBand(
                height=0.5*cm,
                elements=[
                    ObjectValue(attribute_name='product', top=0, left=1*cm),
                    ObjectValue(attribute_name='unit_price', top=0, left=5*cm),
                    ]
                ),
            ),
        ]

And now you have to change the top imports line:

from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
        BAND_WIDTH, Label, ReportGroup, SubReport

The new and most interesting thing here is this:

queryset_string = '%(object)s.purchaseitem_set.all()',

This is the attribute that you use to join the detail object to the subreport. It is a string because you can do a relationship to get objects using different ways.

So, you just use the macro ‘%(object)s’ to set the current object!

Step 1. Preparing your project¶

Let’s create a new URL to load a PDF report online.

We are going to work with a common example for this kind of solution: a purchasing application.

Let’s say you have the following model:

db.define_table(product,
            Field('name', length=100))

db.define_table(customer,
            Field('name', length=100))

db.define_table(purchase,
            Field('customer', db.customer),
            Field('delivery_address', length=70),
            Field('date_creation', 'datetime', default=request.now),
            Field('date_bill', 'date'),
            Field('date_delivery', 'date'),
            Field('taxes', 'float', default=0.00),
            Field('sub_total_price', 'float', default=0.00),
            Field('total_price', 'float', default=0.00)
            )

db.define_table(purchase_item,
            Field('purchase', db.purchase),
            Field('product', db.product),
            Field('unit_price', 'float')
            Field('quantity', 'float')
            Field('total_price', 'float', default=0.00)
            )

Add a new function to your Controller, for example:

def purchase_report():
    from reports import ReportPurchase
    from geraldo.generators import PDFGenerator
    import gluon.contenttype
    import StringIO

    resp = StringIO.StringIO()

    purchases = db(db.purchase.id > 0).select(orderby=db.purchase.customer|db.purchase.id)
    report = ReportPurchase(queryset=purchases)
    report.generate_by(PDFGenerator, filename=resp)

    resp.seek(0)
    response.headers['Content-Type'] = gluon.contenttype.contenttype('.pdf')
    filename = "%s_Purchases.pdf" % (request.env.server_name)
    response.headers['Content-disposition'] = "attachment; filename=\"%s\"" % filename
    return resp.read()

You can see you first imported two important things:

from reports import ReportPurchase
from geraldo.generators import PDFGenerator

Your report class (we will create it in the next step) and the generator class PDFGenerator you will need to generate a PDF file.

The next thing to note is that you instantiate a StringIO object to use to return the PDF:

import StringIO
resp = StringIO.StringIO()

Now you are going to work your report instance:

purchases = db(db.purchase.id > 0).select(orderby=db.purchase.customer|db.purchase.id)
report = ReportPurchase(queryset=purchases)
report.generate_by(PDFGenerator, filename=resp)

Finally you prepare the response:

resp.seek(0)
response.headers['Content-Type'] = gluon.contenttype.contenttype('.pdf')
filename = "%s_Purchases.pdf" % (request.env.server_name)
response.headers['Content-disposition'] = "attachment; filename=\"%s\"" % filename
return resp.read()

• The first thing you did is to get all purchases, ordered by ‘customer’ and ‘id’ fields;
• Afterwards, you got a report instance from your report class ReportPurchase, using purchases queryset as report driver queryset;
• Next, you called the ‘generate_by’ method of the generator class.
• And last, you prepared the StringIO object to be delivered to the browser.

Now you have a prepared Web2Py application to use a report you are going to create at the next step!

Declaring the report class¶

The report class must be an inheritance from geraldo.Report class. You can create a new file ‘reports.py’ to declare your report classes inside.

from geraldo import Report

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

To see something more complex, you can set the page size, margins and other report attributes, like below:

from geraldo import Report, landscape
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

As you can see, we use what we can from the ReportLab libraries, their units, page sizes, stylizing, etc.

A report is driven by bands. If you are used to working with other report engines you know what a band is.

A band is a row with elements in the report canvas. Bands in essence are the same but their use varies depending whether you are using a band as the Page Header or Report Summary, for example.

A report can have a band for each one of following attributes:

Detail band¶

The detail band is the most important band in a report. This is because the detail band is the reason of the existence of every report.

The detail band is used most of the time to show object field values. This is the same for a detailed info page or just a simple list or grid.

The detail band is rendered one time for each object in the queryset attribute. So, if you have 10 objects in the queryset, you will have the detail band rendered 10 times.

Let’s change our report to have a detail band, see below:

from geraldo import Report, landscape, ReportBand, ObjectValue
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

    class band_detail(ReportBand):
        height = 0.5*cm
        elements=(
            ObjectValue(attribute_name='id', left=0.5*cm),
            ObjectValue(attribute_name='date_creation', left=3*cm,
                get_value=lambda instance: instance.date_creation.strftime('%m/%d/%Y')),
            )

The attribute band_detail is locally declared as a class, but it could alternatively be set with an external class.

The important thing here is that the band has the attribute height, fixed with a defined height in centimeters.

The second thing to observe is the elements list, with 2 widgets representing 2 model class fields: id and date_creation. The last one is customized with the get_value attribute, for date field formatting.

Report¶

class geraldo.base.Report¶

Path: geraldo.Report

This is the report main class. Every report must inherit or be an instance of this class. It supports some bands and report definitions.

You can also override some methods to customize some things.

Data source

• queryset - Default: None
• print_if_empty - Default: False

Report properties

• title - Default: ‘’;

• author - Default: ‘’;

• subject - Default: ‘’; (you can use it as the report description)

• keywords - Default: ‘’;

• additional_fonts - Default: {}

  New on 0.4. This is a dictionary where keys have to be the font name and the value have to be the font file path (full path) to support additional true-type fonts inside the PDF. Once you do it, you can use the fone name used on styles as you do with any other default font.

Report page dimensions

• first_page_number - Default: 1
• page_size - Default: A4
• margin_top - Default: 1*cm
• margin_bottom - Default: 1*cm
• margin_left - Default: 1*cm
• margin_right - Default: 1*cm

Report bands

A report band must be a class inherited from ReportBand or an instance of ReportBand or a class inherited from ReportBand

• band_begin - Default: None
• band_summary - Default: None
• band_page_header - Default: None
• band_page_footer - Default: None
• band_detail - Default: None

Report composition

• groups - Default: None
• subreports - Default: []

Look & feel

• default_font_color - Default: black
• default_stroke_color - Default: black
• default_fill_color - Default: black
• default_style - Default: None

Events system

• before_print - Default: None

  Is called by do_before_print method, before render the report. Expect arguments report and generator.

• before_generate - Default: None

  Is called by do_before_generate method, after render report and before to generate the output files. Expect arguments report and generator.

• after_print - Default: None

  Is called by do_after_print method, after generate output files of the report. Expect arguments report and generator.

• on_new_page - Default: None

  Is called by do_on_new_page method, when appending new pages when rendering bands. Expect arguments report, page, page_number and generator.

  Important: if you are setting events as methods, you must name them as “do_” plus event name (i.e. do_before_print). Otherwise, if you are setting them as attributes (setting when creating objects or setting them dinamically) you must name them without “do_”, just their names (i.e. before_print).

Caching related attributes and methods

Take a look on cache documentation to see better explanations.

The attributes cache_status, cache_backend and cache_file_root all have a ‘real’ default None, but they assume values defined on their respective general settings on cache.

• cache_status - Default: geraldo.cache.CACHE_DISABLED

  Can be setted to 3 different values:

  • geraldo.cache.CACHE_DISABLED
  • geraldo.cache.CACHE_BY_QUERYSET
  • geraldo.cache.CACHE_BY_RENDER

• cache_backend - Default: ‘geraldo.cache.FileCacheBacked’

  A string path to class used to set/get reports to cache.

• cache_prefix - Default: report class module + report class name

  Set the prefix for hash key used to identify generated reports from this class.

• cache_file_root - Default: ‘/tmp/’

  The directory path where cached files are stored.

• get_cache_relevant_attributes()

  If you want to set manually what attributes you want to make relevante on cache hash key generation, declare this method to returns a list of the attributes names.

Methods

• format_date(date, expression)

• get_objects_list()

• generate_by(generator_class, *args, **kwargs)

  This is the method used to generate a report to file. Report object is just an abstraction of how report must be like. When generating it to a real file, with real list of objects, you must generate using an generator - a classe from geraldo.generators package.

  Example:

  >>> report = MyReport(queryset=['Rio','London','Beijing'])
  >>> from geraldo.generators import PDFGenerator
  >>> report.generate_by(PDFGenerator, filename='test.pdf')
  

• generate_under_process_by(generator_class, *args, **kwargs)

  Do the same generate_by doest, but uses multiprocessing Process instance to run it. This means it will use a new process to generate the file(s) and will use better the available resources of multi-core servers. In most of cases, also helps to avoid memory consumming.

  But there are servers configured with WSGI with no support to I/O when under separated process and this won’t work properly.

  As all of us know, Python processing is by far a better way to work than threading, so, this helps to solve it.

• find_by_name(name, many=False)

  Find an object with given name in the children (and children of children and so on).

  If you set many to True, if many objects with name are found, all of them are returned, instead, an exception geraldo.exceptions.ManyObjectsFound is raised. The same is valid when none are found, but the exception geraldo.exceptions.ObjectNotFound is raised.

• find_by_type(typ)

  Find a list of objects that are instance of class given. As same as find_by_name, children of children and so on are found too.

SubReport¶

class geraldo.base.SubReport¶

Path: geraldo.SubReport

Class to be used for subreport objects. It doesn’t need to be inherited.

Attributes

• queryset_string - must be a string to create a Python-compatible queryset.

  Examples:

  • ‘%(object)s.user_permissions.all()’
  • ‘%(object)s.groups.all()’
  • ‘Message.objects.filter(user=%(object)s)’
  • ‘Message.objects.filter(user__id=%(object)s.id)’

• visible - Default: True

  Set to False if you want to make it not visible.

Report bands

A report band must be a class inherited from ReportBand or an instance of ReportBand or a class inherited from ReportBand

• name - Default: None
• band_detail - Default: None
• band_header - Default: None
• band_footer - Default: None

Methods

• format_date(date, expression)
• get_objects_list()

ReportBand¶

class geraldo.base.ReportBand¶

Path: geraldo.ReportBand

A band is a horizontal area in the report. It can be used to print things on the top, on summary, on page header, on page footer or one time per object from queryset.

Attributes

• name - Default: None

• height - Default: 1*cm

• width - Default: None

• visible - Default: True

  Set to False if you want to make it not visible.

• borders - Default: {‘top’: None, ‘right’: None, ‘bottom’: None, ‘left’: None, ‘all’: None}

  Borders values can be of three types:

  • Boolean (True/False) - just set if there is a border or not
  • Integer - set there is a border and what is its stroke width. New on 0.4.
  • Graphic (instance of Rect, Line, RoundRect, etc.) - set a complex graphic to put along the border

• elements - Default: []

• child_bands - Default: []

• force_new_page - Default: False

• default_style - Default: None

• margin_top - Default: 0

• margin_bottom - Default: 0

• auto_expand_height - Default: False

  Use ‘auto_expand_height’ to make flexible bands to fit their heights to their elements.

DetailBand¶

class geraldo.base.DetailBand¶

Path: geraldo.DetailBand

An extension of ReportBand. The only difference is that this class supports more attributes, specific to detail bands.

Attributes

• name - Default: None

• margin_left - Default: 0

• margin_right - Default: 0

• display_inline - Default: False

  When you use display_inline with True value and width with a valid value, the generator will try to align the detail band instances in the same way that HTML does with inline displaying of left floating elements: it will keep each detail band to the right of the last one if there is width available.

  This is useful for label reports.

ReportGroup¶

class geraldo.base.ReportGroup¶

Path: geraldo.ReportGroup

This a report grouper class. A report can be grouped to multiple levels by attribute values.

Attributes

• name - Default: None
• attribute_name - Default: None
• force_new_page - Default: False

Report bands

A report band must be a class inherited from ReportBand or an instance of ReportBand or a class inherited from ReportBand

• band_header - Default: None
• band_footer - Default: None

ManyElements¶

class geraldo.base.ManyElements¶

Path: geraldo.ManyElements

New on 0.4.

This class is a factory that makes many elements using pre-defined arguments. It is useful to make Cross-Reference Tables, because this is the situation when you almost never know how many columns you ned.

Attributes

• element_class - Default: None

  The element class you are going to used to create the instances. i.e: Label, ObjectValue, etc.

• count - Default: None

  How many elements do you want to create?

• start_left - Default: 0

  The left value for the forst element (because it will be incremented with width values for each one.

• start_top - Default: 0

  The same of ‘start_left’, but for top/height relation;

• visible - Default: None

  Make the ManyElements not visible and their elements will be also.

The attributes above are just for the class control to make the elements.

But this class supports other attributes, that will be passed to elements it will create. These attributes must be passed when initializing the class, as common arguments like everyone else. Example: you can use ManyElements like below:

>>> ATTRIBUTES_LIST = ('date_start', 'date_end', 'salary', 'hours')
>>> band_elements = [
...     ObjectValue(attribute_name='job'),
...     ManyElements(element_class=ObjectValue, count=4, start_left=3*cm,
...         width=1*cm, attribute_name=ATTRIBUTES_LIST),
... ]

As you can see, there are 3 special attributes (element_class, count and start_left), there is also a simple value for ‘width’ attribute, and ‘attribute_name’ receives a list.

ManyElements is smart enough to know that the attribute had a simple value or a list and use the list in the same sequence of creation (if the list is shorter, the latest item will be used), otherwise that value will be copied to all the created elements.

The attribute ‘left’ will be increased, starting from ‘start_left’ plus ‘width’ for each column.

Result: when rendering, Geraldo will create 4 new elements from the factory.

Methods

• get_elements(cross_cols=None)

  This is the method that creates the elements and returns them.

Widget¶

class geraldo.widgets.Widget¶

Path: geraldo.widgets.Widget

Base class for reports widgets, you should use it only to inherit and make your own widgets, otherwise you shouldn’t use it directly.

Attributes

• name - Default: None

• height - Default: 0.5*cm

• width - Default: 5*cm

• left - Default: 0

• top - Default: 0

• visible - Default: True

  Set to False if you want to make it not visible.

• borders - Default: {‘top’: None, ‘right’: None, ‘bottom’: None, ‘left’: None, ‘all’: None}

  Borders values can be of three types:

  • Boolean (True/False) - just set if there is a border or not
  • Integer - set there is a border and what is its stroke width. New on 0.4.
  • Graphic (instance of Rect, Line, RoundRect, etc.) - set a complex graphic to put along the border

• style - Default: {}

  This is a dictionary that uses the powerful ReportLab ParagraphStyle class to set style settings for this widget.

  Default keys are:

  • fontName - Default: ‘Times-Roman’,
  • fontSize - Default: 10,
  • leading - Default: 12,
  • leftIndent - Default: 0,
  • rightIndent - Default: 0,
  • firstLineIndent - Default: 0,
  • alignment - Default: TA_LEFT,
  • spaceBefore - Default: 0,
  • spaceAfter - Default: 0,
  • bulletFontName - Default: ‘Times-Roman’,
  • bulletFontSize - Default: 10,
  • bulletIndent - Default: 0,
  • textColor - Default: black,
  • backColor - Default: None,
  • wordWrap - Default: None,
  • allowWidows - Default: 1,
  • allowOrphans - Default: 0,

• get_value - Default: None.

  This is the way you can easily customize the widget output. Be careful with this attribute, because each widget has its own set of arguments.

• truncate_overflow - Default: False

  When “True”, truncate the widget to use only its defined height and widget attributes, with no word wrap. This means that those attributes are required.

Events system

• before_print - Default: None

  Is called by do_before_print method, before generate the widget output. Expect arguments widget and generator.

• after_print - Default: None

  Is called by do_after_print method, after generate the widget output. Expect arguments widget and generator.

Rendering attributes

They are read-only attributes you can use at render time.

• instance - current object being rendered
• generator - generator instance
• report - report instance this element is in
• band - band this element is in
• page - current page

Label¶

class geraldo.widgets.Label¶

Path: geraldo.Label

A label is just a simple text.

Example of use

>>> Label(text='Taxes we have paid', left=1*cm, top=0.5*cm, width=10*cm, height=0.5*cm)

Attributes

• height - Default: 0.5*cm
• width - Default: 5*cm
• left - Default: 0
• top - Default: 0
• visible - Default: True
• style - Default: {}

get_value must have a ‘text’ argument.

ObjectValue¶

class geraldo.widgets.ObjectValue¶

Path: geraldo.ObjectValue

This shows the value from a method, field or property from objects in the queryset.

You can provide an action to show the object value or an aggregation function on it.

You can also use the ‘display_format’ attribute to set a friendly string formatting, with a mask or additional text.

‘get_value’ lambda must have an ‘instance’ argument.

Example of use

>>> ObjectValue(attribute_name='name', left=1*cm, top=0.5*cm, width=10*cm, height=0.5*cm)

Attributes

• height - Default: 0.5*cm

• width - Default: 5*cm

• left - Default: 0

• top - Default: 0

• visible - Default: True

• style - Default: {}

• attribute_name - Required

  You can provide here the object attribute name you want to show in this widget. You can provide a field, common attribute, property or just a method, since it has no required argument to provide.

  You can use paths of callable or properties instead of attribute name in this attribute.

  Examples:

  attribute_name = ‘name.upper’ attribute_name = ‘customer.name’ attribute_name = ‘customer.type.name.lower’

• action - Default: geraldo.FIELD_ACTION_VALUE

  The action is where you say what Geraldo will do with the value of this field. The default action is just to show its value and nothing more.

  But if you are using an ObjectValue in a summary or footer band of report, group or subreport, you will probably have a need for aggregation functions. This is why this attribute exists.

  Field actions are all available in the geraldo package to import from. The choices you can use in action attributes are:

  • geraldo.FIELD_ACTION_VALUE
  • geraldo.FIELD_ACTION_COUNT
  • geraldo.FIELD_ACTION_AVG
  • geraldo.FIELD_ACTION_MIN
  • geraldo.FIELD_ACTION_MAX
  • geraldo.FIELD_ACTION_SUM
  • geraldo.FIELD_ACTION_DISTINCT_COUNT

• display_format - Default: ‘%s’

  Use simple string formatting on the field value. You could otherwise use get_value if you want something more powerful.

• get_text - Default: None.

  This ‘lambda’ attribute is seemed to get_value because it works after value getting. It’s important to keep aware there are two moments from get a value from instance until to render it on the output generation:

  • 1. First the value is getted (and keeps being an unformatted value)
  • 2. After this, the value is formatted (and transformed to unicode string)

• stores_text_in_cache - Default: True

  This is a boolean attribute you can set to False if you to force the text getting to run twice: on renderizing and on generating. If you keep it as True, it will store the text on the first getting and use the stored text on next time(s) it be requested.

Events system

• on_expression_error - Default: None

  Is called when Geraldo tries to interpret an expression and an exception is raised. It must be a function with the following arguments:

  • widget (or just ‘self’)
  • exception (or just ‘e’)
  • expression (or just ‘expr’)
  • instance (or just ‘inst’)

  This function can returns a default value or just call ‘raise’ to raise the same exception.

SystemField¶

class geraldo.widgets.SystemField¶

Path: geraldo.SystemField

This shows system information, like the report title, current date/time, page number, page count, etc.

‘get_value’ must have ‘expression’ and ‘fields’ arguments.

Example of use

>>> ObjectValue(expression='%(report_title)s', left=1*cm, top=0.5*cm, width=10*cm, height=0.5*cm)

Attributes

• height - Default: 0.5*cm

• width - Default: 5*cm

• left - Default: 0

• top - Default: 0

• visible - Default: True

• style - Default: {}

• expression - Default: ‘%(report_title)s’

  This is a simple string you can write with basic macros to show system field values.

  The available macros are:

  • %(report_title)s

  • %(page_number)s

  • %(first_page_number)s

  • %(last_page_number)s

  • %(page_count)s

  • %(report_author)s

  • %(now:FORMAT)s - in replace of ‘FORMAT’ you can use date formatting standard template filter date formatting. But if you are using your own Report.format_date method, this will use it.

    Examples:

    • ‘%(now:%Y)’ - shows the current year
    • ‘%(now:%m/%d/%Y)’ - shows something like ‘01/23/2009’

    Note: this is changed now. Before this function used Django template filter ‘date’ to format datetime, but once we were going to use two standards, this wouldn’t be nice. If you want to use Django’s template filter, you can override the method Report.format_date(date, expression) and use it.

  • %(var:VARIABLE_NAME)s - you can inform a variable here and declare it when call generator, like the example below:

    SystemField(expression=’%(var:filter)s’) ... report.generate_by(PDFGenerator, variables={‘filter’: ‘My Filter’})

Graphic¶

class geraldo.graphics.Graphic¶

Path: geraldo.graphics.Graphic

This is the basic graphic class. You should use it only when inheriting to create your own graphic class, never use it directly.

Its rect area is based on left-width-top-height dimensions.

Attributes

• name - Default: None

• visible - Default: True

  Set to False if you want to make it not visible.

• stroke - Default: True

• stroke_color - Default: reportlab.lib.colors.black

• stroke_width - Default: 1

• fill - Default: False

• fill_color - Default: reportlab.lib.colors.black

Rendering attributes

They are read-only attributes you can use at render time.

• instance - current object being rendered
• generator - generator instance
• report - report instance this element is in
• band - band this element is in
• page - current page

Events system

• before_print - Default: None

  Is called by do_before_print method, before generate the graphic output. Expect arguments graphic and generator.

• after_print - Default: None

  Is called by do_after_print method, after generate the graphic output. Expect arguments graphic and generator.

Methods

• set_rect(**kwargs)

  Used to generate a hard rectangle when rendering pages. Override it to set your own rule if you need.

Fixed¶

class geraldo.graphics.Fixed¶

Path: geraldo.graphics.Fixed

In the same way as Graphic class, you should use this just to inherit and create your own graphic. This is a graphic with rect with left-right-top-bottom dimensioning.

Rect¶

class geraldo.graphics.Rect¶

Path: geraldo.Rect

A rectangle with square borders on the canvas.

Example of use

>>> Rect(left=1*cm, top=0.5*cm, width=10*cm, height=0.5*cm, fill=True, fill_color=yellow)

Attributes

• left - Required
• width - Required
• top - Required
• height - Required

RoundRect¶

class geraldo.graphics.RoundRect¶

Path: geraldo.RoundRect

A rectangle with rounded borders on the canvas.

Example of use

>>> RoundRect(left=1*cm, top=0.5*cm, width=10*cm, height=0.5*cm, stroke=True, stroke_width=3, stroke_color=blue)

Attributes

• left - Required

• width - Required

• top - Required

• height - Required

• radius - Required

  Inform the radius number for the round corners.

Line¶

class geraldo.graphics.Line¶

Path: geraldo.Line

Example of use

>>> Line(left=1*cm, top=0.5*cm, right=10*cm, bottom=0.5*cm)

Attributes

• left - Required
• width - Required
• right - Required
• bottom - Required

Circle¶

class geraldo.graphics.Circle¶

Path: geraldo.Circle

Example of use

>>> Circle(left_center=6*cm, top_center=3.5*cm, radius=3*cm)

Attributes

• left_center - Required
• top_center - Required
• radius - Required

Arc¶

class geraldo.graphics.Arc¶

Path: geraldo.Arc

Example of use

>>> Arc(left=1*cm, top=0.5*cm, right=10*cm, bottom=0.5*cm, extent=50, start_angle=5)

Attributes

• left - Required
• width - Required
• right - Required
• bottom - Required
• start_angle - Default: 0
• extent - Default: 90

Ellipse¶

class geraldo.graphics.Ellipse¶

Path: geraldo.Ellipse

Example of use

>>> Ellipse(left=1*cm, top=0.5*cm, right=10*cm, bottom=0.5*cm)

Attributes

• left - Required
• width - Required
• right - Required
• bottom - Required

Image¶

class geraldo.graphics.Image¶

Path: geraldo.Image

Example of use

>>> Image(left=1*cm, top=0.5*cm, right=10*cm, bottom=0.5*cm, filename='path/to/file.jpg')

Attributes

• left - Required

• width - Required

• top - Required

• height - Required

• filename - Required

  You can provide a filename path or a Python Imaging Library Image instance. If the latter, then you have to have this library installed.

• get_image - Default: None

  You should provide a function or lambda object to this attribute when you want to work with Images or Charts based on object values or logic.

BarCode¶

class geraldo.barcodes.BarCode¶

Path: geraldo.barcodes.BarCode

This is the once class you can use to show bar codes. It supports the following bar code types, supplied by ReportLab barcodes library:

• Codabar
• Code11
• Code128
• EAN13
• EAN8
• Extended39
• Extended93
• FIM
• I2of5
• MSI
• POSTNET
• Standard39
• Standard93
• USPS_4State

Attributes

• name - Default: None

• visible - Default: True

  Set to False if you want to make it not visible.

• height - Default: 1.5*cm

• width - Default: 0.03*cm

  This attribute does not set the barcode width, but the bar width, what means it is the width of the minimum bar of a barcode. You should set values like 0.02*cm or something like that (i.e. never 5*cm).

• attribute_name - Default: None

  As same as geraldo.widgets.ObjectValue, this attribute reffers to an attribute, attribute path or method to get the barcode value.

• checksum - Default: 0

  Most of barcode types supports you set the number of digits for checksum.

• routing_attribute - Default: None

  Useful only for USPS_4State barcodes. Works like attribute_name, but routing attribute of barcode.

Rendering attributes

They are read-only attributes you can use at render time.

• instance - current object being rendered
• generator - generator instance
• report - report instance this element is in
• band - band this element is in
• page - current page

CrossReferenceMatrix¶

class geraldo.cross_reference.CrossReferenceMatrix¶

Path: geraldo.CrossReferenceMatrix

The Solution

As you can realize, this is not an easy job, because you never know how many columns you will have, and there are many ways to collect cross-reference data.

Some RDBMS’s offers out of box ways to get a cross-reference among three fields in a select, but this is not only limited but is also not a definitive solution, because even if you have the matrix of data, you still have to prepare all elements on the report you are going to print.

The solution on Geraldo is the class ‘geraldo.cross_reference.CrossReferenceMatrix’.

To instantiate this class, you must inform the objects list (not necessarily a matrix, because you can just give a Django queryset, or a list of dictionaries) and the names of the X and Y attributes (row_attribute and col_attribute).

Once you create that instance, you can call many methods from it to get aggregated values, giving the third attribute you want to aggregate, and the filter for row and column directions.

This instance can be used out of Geraldo’s functions, like a template, e-mails, text files, whatever, it is not dependent on reports to work.

Methods

• __init__(objects_list, rows_attribute, cols_attribute)

  When you make an instance of CrossReferenceMatrix, you must inform the objects list and the attributes to cross: rows_attribute (X) and cols_attribute (Y).

• rows()

  Returns the values of row attribute in objects list, that means you get the list of rows on the matrix.

• cols()

  Returns the values of column attribute on objects list, that means you get the list of columns on the matrix.

• values(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  Returns the values (a list of them) crossed between a row and a column. If you just let the argument ‘row’ or ‘col’ with default value, it will get all values according to the filter you informed (i.e. if you just informed the ‘col’, you will get all values for that col, in the sequence of the available rows).

  This method is used by all of the others below.

• max(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘values’, but this find the maximum value for that relation and returns it.

• min(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘max’, but returns the minimum value of them.

• sum(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘max’, but returns the sum of found values.

• avg(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘max’, but returns the average of found values.

• count(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘max’, but returns the count of found values.

• distinct_count(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘count’, but returns the count of not redundant values.

• first(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  Just returns the first value found for the relation.

• last(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)

  As same as method ‘first’, but returns the last value.

• matrix(cell, func=’values’)

  Returns a matrix with rows and columns with cross table values (including headers).

PDF Generator¶

class geraldo.generators.PDFGenerator¶

Path: geraldo.generators.PDFGenerator

This generator is the most mature generator we have. It generates PDF files to be viewed on Adobe Acrobat Reader or similar software. It uses the awesome library ‘ReportLab’ to create them.

Attributes:

• first_page_number - Default: 1

  Set a different number to this attribute if you want to start page counting from a customized number.

• filename - Default: None

  You have to provide the filename you are creating, unless you provided the attribute ‘canvas’

• canvas - Default: None

  New in version 0.3.5

  If you already have a canvas instantiated, you can provide it instead of ‘filename’ to generate this report inside. This is useful to generate many reports in the same PDF.

• return_canvas - Default: False

  New in version 0.3.5

  If you set this to True, the file will not be saved and the generator will return the canvas to you to use as you want.

• multiple_canvas - Default: False

  New in version 0.3.7

  This attribute has default value True if you have pyPDF library installed on your PYTHONPATH.

  It is useful to store canvas in a temporary directory and combine all in once when finished the generating. This helps to gain on memory consuming.

  You can find more about pyPDF on http://pypi.python.org/pypi/pyPdf/

• temp_directory - Default: ‘/tmp/’

  Regarding to temporary saving files on report processing, this attribute can receive a string with directory path where save those files.

To use PDFGenerator you just do something like this:

>>> my_report_instance.generate_by(PDFGenerator, filename='file.pdf')

In filename argument you can use a file path string or a file output object.

Examples:

>>> fp = file('test.pdf', 'w')
>>> my_report_instance.generate_by(PDFGenerator, filename=fp)
>>>
>>> resp = HttpResponse(mimetype='application/pdf')
>>> my_report_instance.generate_by(PDFGenerator, filename=resp)

Text Generator¶

class geraldo.generators.TextGenerator¶

Path: geraldo.generators.TextGenerator

This generator is still in the development stage, but it already works well. It can be used to generate text files or to print to matrix printers.

You can use it exactly like you would use PDF generator, but this has some more features. When running ‘generate_by’ report method, you can inform the attribute ‘filename’ like you do in PDF, but you could also do some other things.

Attributes:

• row_height - Default: 0.5*cm

  Should be the equivalent height of a row plus the space between rows. This is important to calculate how many rows a page has.

• character_width - Default: 0.23*cm

  Should be the equivalent width of a character. This is important to calculate how many columns a page has.

• to_printer - Default: True

  Is a boolean variable which you can set to generate a text to matrix printer or not. This controls whether escape characters will be in the output or not.

• escape_set - Default: geraldo.generators.text.DEFAULT_ESCAPE_SET

  Is a dictionary with equivalence table to escape codes. As far as we know, escape codes can vary depending on model or printer manufacturer (i.e. Epson, Lexmark, HP, etc.). This attribute is useful to support this. Default is ESC/P2 standard (Epson matrix printers)

• filename - Default: None

  Is the file path you can optionally provide to save text to.

• encode_to - Default: None

  Here you can provide the coding identifier to force Geraldo to encode the output string in. Example: ‘latin-1’

• manual_escape_codes - Default: False

  A boolean variable that sets whether escape codes are manually provided or not.

Examples:

Basic:

>>> my_report_instance.generate_by(TextGenerator, filename='file.txt')

Returning the output:

>>> output = my_report_instance.generate_by(TextGenerator)

Setting row height and/or column width:

>>> output = my_report_instance.generate_by(TextGenerator, row_height=0.7*cm, character_width=0.2*cm)

Forcing the generator to encode the output:

>>> output = my_report_instance.generate_by(TextGenerator, encode_to='latin-1')

Setting to be printed by a printer or not:

>>> output = my_report_instance.generate_by(TextGenerator, to_printer=False)

Setting a set of escape codes for printer (matrix printers work with escape codes set for special characters or to setup the output printing):

>>> from geraldo.generators.text import DEFAULT_ESCAPE_SET
>>> my_escape_set = DEFAULT_ESCAPE_SET.copy()
>>> my_escape_set['condensed'] = chr(15) + chr(17)
>>> output = my_report_instance.generate_by(TextGenerator, to_printer=True, escape_set=my_escape_set)

Forcing the output to print out escape codes before/after report or page print:

>>> MyTextGenerator(TextGenerator):
...     to_printer = True
...     manual_escape_codes = True
...     escapes_report_start = chr(15) # Sets condensed mode
...     escapes_report_end = chr(18) # Unsets condensed mode
...     escapes_page_start = chr(12) + chr(10) # Form and line feed
...     escapes_page_end = ''
>>> output = my_report_instance.generate_by(MyTextGenerator)

CSV Generator¶

class geraldo.generators.CSVGenerator¶

Path: geraldo.generators.CSVGenerator

This generator is still in the development stage, but it already works well. It just makes a CSV (comma separated values) file with details band ObjectValue elements, ordered by their left positions.

Attributes:

• writer - Default: None

  If you want to customize the CSV writer, set this with an object with same methods that an instance that Python’s csv.writer returns.

• writer_function - Default: csv.writer

  You can also set this attribute with a function that waits for a file object as its only argument and returns a writer instance.

• first_row_with_column_names - Default: False

  To append a first row with column names, set this to True.

Settings¶

All of the following settings are generic and are used by respective ones in each report class, and there they can be overridden too.

• DEFAULT_CACHE_STATUS - Default: geraldo.cache.CACHE_DISABLED

  This setting can receive three different types of status:

  • geraldo.cache.CACHE_DISABLED

    Just disables the caching at all.

  • geraldo.cache.CACHE_BY_QUERYSET

    Enable the caching function to use queryset values as the base to generate a hash key and store in the cache. You must use this if the most important thing for you is the data in the report. By the way, this choice is the fastest one.

  • geraldo.cache.CACHE_BY_RENDER

    Enable the caching function to use the rendered objects as the base to generate a hash key and store in the cache. You must use this if you want to consider style and feel when storing to cache. This is not the fastest but probably the most reliable.

• CACHE_BACKEND - Default: ‘geraldo.cache.FileCacheBackend’

  Just inform the full string path to a backend class.

• CACHE_FILE_ROOT - Default: ‘/tmp/’

  Just inform (if you are using the FileCacheBackend backend) the path of directory where you want to store the cache files.

Classes¶

• FileCacheBackend

  This is the default (and the only one Geraldo supplies) cache backend. It stores files in a directory on the file system (hard disk).

  You can extend this class if you want to tun up the file system caching.

• BaseCacheBackend

  If you want to extend cache to a different kind of cache store (i.e. memcache, database or someone else), you have to make a class inheriting from this one.

  Basically you must set three methods:

  • get(hash_key)
  • set(hash_key, content)
  • exsts(hash_key)

landscape¶

geraldo.utils.landscape()¶

Path: geraldo.landscape

Page sizes are tuples with 2 nodes: first with width and second width height.

landscape is a helper function to invert this tuple.

BAND_WIDTH¶

geraldo.utils.BAND_WIDTH¶

Path: geraldo.BAND_WIDTH

Once you use this constant in a widget or graphic width, it will assume its band width automatically.

memoize¶

geraldo.utils.memoize()¶

Path: geraldo.utils.memoize

This is a decorator used internally by some functions to store their result values like a cache. When the same function is called again with same arguments values, the stored value is returned, instead of run its code again.

You can use it for your own code, just wrapping your function under the decorator.

Example of use:

>>> from geraldo.utils import memoize
>>> @memoize
... def calc_sum(val1, val2):
...     return val1 + val2

run_under_process¶

geraldo.utils.run_under_process()¶

Path: geraldo.utils.run_under_process

This is a decorator supplied by Geraldo to help developers to run functions under a new process instead of the main thread.

Geraldo uses it in method Report.generate_under_process_by, to run the report generation under other process, but you can use it on your own code, if you don’t want/can’t use that method.

Example of use:

>>> from geraldo.generators import PDFGenerator
>>> from geraldo.utils import run_under_process
>>> @run_under_process
... def generate_by_report(report, filename):
...     report.generate_by(PDFGenerator, filename=filename)

DISABLE_MULTIPROCESSING¶

geraldo.utils.DISABLE_MULTIPROCESSING¶

Path: geraldo.DISABLE_MULTIPROCESSING

A short way to disable all use of multiprocessing on Geraldo, at all. This is useful when you are debugging your reports.