Magazine documentation¶

class magazine.magazine.Magazine¶

Can be used to log information in a human-readable way. Supports different report topics. The list of topics can be later posted as a composite string. Useful for writing reports with class Publish().

Examples

>>> Magazine.report("observations", "Temperature today was {:.2f}.", None)
... Magazine.report("observations", "Data was corrected following {:}, only {:d} points remained.", "Brown et al. (1979)", 42)
... Magazine.post("observations")
Temperature today was nan. Data was corrected following Brown et al. (1979), only 42 points remained.

static assert_topic(topic: str)¶

Makes sure that the topic exists in dict before appending. Intialized as empty list per topic.

Parameters:: topic (str) – Name of an existing or new topic

Examples

>>> Magazine.assert_topic("Experiments")
... Magazine.topics["Experiments"]
[]

static cite(*refs)¶

Appends a reference to the Magazine that can be later converted to a reference list.

Parameters:: *refs (str) – Any number of reference texts. If it looks like a doi, it will be stored in a separate list which is used to download full texts by collect_references().

Examples

>>> Magazine.cite("10.5194/hess-27-723-2023", "10.1029/2021gl093924")
>>> Magazine.cite("Einstein, A. (1916). Die Grundlage der allgemeinen Relativitätstheorie. Annalen Der Physik, 354(7), 769–822. Portico")

static clean()¶: Cleans topics, figures, references, and dois to make space for a new Magazine.

static collect_references() → list¶

Lists all items in Magazine.references. Downloads the full reference text for all items in Magazine.dois

Returns:: List of reference texts, sorted by name.
Return type:: list

Examples

>>> for item in Magazine.collect_references():
...     print(item)

static figure(*topics) → list¶

Joins the topic’s figures to a combined flat list.

Parameters:: *topics (str) – Any number of existing topics
Returns:: Merged topic figures.
Return type:: list

Examples

>>> all_figures = Magazine.figure("Experiments", "Methods")

static new()¶: Cleans topics, figures, references, and dois to make space for a new Magazine.

static post(*topics) → str¶

Joins the topic’s list on a single space.

Parameters:: *topics (str) – Any number of existing topics
Returns:: Merged topic texts.
Return type:: str

Examples

>>> paragraph = Magazine.post("Experiments", "Methods")

static report(topic='default', message='', *values)¶

Appends a text or image to the topic’s list. The text is checked for Nonetype values before.

Parameters:

topic (str) – Name of an existing or new topic
message (str | io.BytesIO) – Text or bytes object (to store figures)
*values – Any number of values to be inserted into the formatted message

Examples

>>> Magazine.report("Experiments", "Today is {}.", "Monday")

static turn_off()¶: Truns off Magazine reporting

static turn_on()¶: Turns on Magazine reporting

class magazine.magazine.SafeDict¶

A variant of dict that does not raise an error for missing keys. Thanks to: https://stackoverflow.com/a/17215533/2575273

Example

>>> parameters = SafeDict(a=1, b=2)
... print(parameters["a"], parameters["c"])
1 {c}

class magazine.publish.PDF(title: str = '', info: str = '', datetime_fmt: str = '', page_numbers: bool = True)¶

PDF writer and wrapper for FPDF

Examples

>>> pdf = PDF()
... pdf.header_text = "My title"
... pdf.add_page()
... pdf.output("my_title.pdf")

Notes

Thanks to: https://py-pdf.github.io/fpdf2/Maths.html

add_figure(topic: str = None, headers: bool = False, new_page: bool = False)¶

Write all figures of a topic to the PDF.

Parameters:

topic (str, optional) – Existing topic, by default None
headers (bool, optional) – Add a topic headline before the figure, by default False
new_page (bool, optional) – Create a new page, by default False

Examples

>>> image_object = io.BytesIO()
... plt.savefig(image_object, format="svg")
... Magazine.report("Experiments", image_object)
... with Publish("example.pdf") as M:
...     M.add_figure("Experiments")

add_head(title: str = None, style: str = 'B')¶

Add a chapter title.

Parameters:

title (str) – Title of the page, can be empty.
style (str, optional) – Font style, is “B” for bold by default.

Examples

>>> with Publish("example.pdf") as M:
...     M.add_title("My title")

add_image(source=None, x: float = None, y: float = None, w: float = None, h: float = 0, link: str = '')¶

Write an image to PDF.

Parameters:

source (string or object or list of objects, optional) – Can be a file path (png, jpg) or an image buffer or a list of them., by default None
x (float, optional) – x coords of image, by default None
y (float, optional) – y coords of image, by default None
w (float, optional) – width of image, by default None
h (float, optional) – height of image, scales automatically with width, by default 0
link (str, optional) – link for the image, by default “”

Examples

>>> image_object = io.BytesIO()
... plt.savefig(image_object, format="svg")
... with Publish("example.pdf") as M:
...     M.add_image(image_object)
...     M.add_image("image_file.png")

add_paragraph(text: str = None)¶

Add a multiline paragraph.

Parameters:: text (str) – Text to be written.

Examples

>>> with Publish("example.pdf") as M:
...     M.add_paragraph("Very long text.")

add_references(headers: str = 'References', new_page: bool = True)¶

Create a list of references that were previously added by Magazine.cite() This function will look up the full citations text using the habanero package.

Parameters:

headers (str, optional) – Title of the references page, by default “References”
new_page (bool, optional) – Whether or not to add a new page, by default True

Examples

>>> Magazine.cite("10.1029/2021gl093924")
... with Publish("example.pdf") as M:
...     M.add_references()

add_table(data: DataFrame = None, align: str = 'RIGHT', index: bool = False, font_size=7, last_column_first=True)¶

Add a table for a pandas DataFrame.

Parameters:

data (pd.DataFrame, optional) – DataFrame to print to the PDF, by default None
align (str, optional) – Alignment of the cell text, by default “RIGHT”
index (bool, optional) – Whether or not to display the index column, by default False

Examples

>>> data = pd.DataFrame({"name":["Tim", "Tom"], "age":[12,13]})
... with Publish("example.pdf") as M:
...     M.add_table(data, index=True)

add_text(text: str = None)¶

Add a multiline paragraph.

Parameters:: text (str) – Text to be written.

Examples

>>> with Publish("example.pdf") as M:
...     M.add_paragraph("Very long text.")

add_title(title: str = None, style: str = 'B')¶

Add a chapter title.

Parameters:

title (str) – Title of the page, can be empty.
style (str, optional) – Font style, is “B” for bold by default.

Examples

>>> with Publish("example.pdf") as M:
...     M.add_title("My title")

add_topic(topic: str = None, headers: bool = True, new_page: bool = True)¶

Shortcut to add a page, title, and topic text.

Parameters:

topic (str) – Topic to take the report from.
headers (bool, optional) – Write a headline, by default True
new_page (bool, optional) – Create a new page, by default True

Examples

>>> with Publish("example.pdf") as M:
...     M.add_topic("Experiments")

header()¶: Overwrites the FPDF’s header function with a table: | %title | %info | %datetime | %page |

class magazine.publish.Publish(filename: str, title: str = '', info: str = '', datetime_fmt: str = '%Y-%m-%d %H:%M', page_numbers: bool = True)¶

Context manager to write all reports, figures, and references into a PDF file. Uses FPDF2 to return a PDF class.

Parameters:

filename (str) – Full path and name of the PDF file.
title (str, optional) – Title to be written in the header, by default “”
info (str, optional) – Any info to be written in the header, e.g. a version number, by default “”
datetime_fmt (str, optional) – How to format the datetime in the header, by default “%Y-%m-%d %H:%M”
page_numbers (bool, optional) – Whether or not to show page numbers, by default True

Returns:

An instance that inherits from fpdf.FPDF to provide commands to add content to the PDF.

Return type:

PDF

Examples

>>> with Magazine.Publish("example.pdf", "My Title") as M:
...     M.add_page()
...     M.add_title("Chapter 1)
...     M.add_paragraph("Long text")
...     M.add_image(figure)
...     M.add_table(data)

Magazine documentation¶

Table of Contents

This Page