diff --git a/docs/History.md b/docs/History.md index 77283d0e1..d8041601b 100644 --- a/docs/History.md +++ b/docs/History.md @@ -1,10 +1,6 @@ # History # -This project, `fpdf2` is a _fork_ of the `PyFPDF` project, which can be found -[on GitHub at reingart/pyfpdf](https://github.com/reingart/pyfpdf) -but has been inactive since January of 2018. - -On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: https://github.com/py-pdf/fpdf2. The context for this move can be found there: https://github.com/py-pdf/fpdf2/discussions/752. On this date, the `PyFPDF` GitHub organization has been **archived**. +This project, `fpdf2` is a _fork_ of the `PyFPDF` project, which can still be found [on GitHub at reingart/pyfpdf](https://github.com/reingart/pyfpdf), but has been totally inactive since January 2018, and has not seen any new release since 2015. About the original `PyFPDF` lib: @@ -13,13 +9,49 @@ About the original `PyFPDF` lib: > Later, code for native reading TTF fonts was added. > The project aim is to keep the library up to date, to fulfill the goals of its > [original roadmap](https://github.com/reingart/pyfpdf/wiki/Roadmap) and provide -> a general overhaul of the codebase to address technical debt keeping features from being added -> and bugs to be eradicated. +> a general overhaul of the codebase to address technical debt keeping features from being added and bugs to be eradicated. > Until 2015 the code was developed at [Google Code](https://code.google.com/p/pyfpdf/): > you can still access the [old issues](https://github.com/reingart/pyfpdf_googlecode/issues), > and [old wiki](https://github.com/reingart/pyfpdf_googlecode/tree/wiki). -As of version [2.5.4](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md), -`fpdf2` is fully backward compatible with PyFPDF, with the exception of one minor point: -for the [`cell()` method](fpdf/fpdf.html#fpdf.fpdf.FPDF.cell), the default value of `h` has changed. -It used to be `0` and is now set to the current value of `FPDF.font_size`. +## How fpdf2 came to be ## + +During the spring of 2016, David Ankin (`@alexanderankin`) started a fork of PyFPDF, and added the first commit of what became `fpdf2`: +[bd608e4](https://github.com/py-pdf/fpdf2/commits/master?after=1db5f7fdc93eac981c8f1d15856649b68e523ec8+69&branch=master&qualified_name=refs%2Fheads%2Fmaster). +On May of 2017, the first release of `fpdf2` was published on Pypi: +[v2.0.0](https://pypi.org/project/fpdf2/#history). + +On 2020, the first PRs were merged from external contributors. +At the end of the year, Lucas Cimon (`@Lucas-C`) started contributing several improvements. +[Version **2.1.0** was released](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md#210---2020-12-07) and soon after `@Lucas-C` became another maintainer of the project. + +On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: . The context for this move can be found there: . On this date, the `PyFPDF` GitHub organization has been **archived**. + +## Compatibility between PyFPDF & fpdf2 ## + +`fpdf2` aims to be fully compatible with PyFPDF code. + +The notable exceptions are: + +* for the [`cell()` method](fpdf/fpdf.html#fpdf.fpdf.FPDF.cell), the default value of `h` has changed. It used to be `0` and is now set to the current value of `FPDF.font_size` +* the font caching mechanism, that used the `pickle` module, has been **removed**, for security reasons, and because it provided little performance gain, and only for specific use cases - _cf._ [issue #345](https://github.com/py-pdf/fpdf2/issues/345). +* [Template](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template) elements now have a **transparent background** by default, instead of white + +Some features are also **deprecated**. As of version 2.7.5 they **still work** but **generate a warning** when used: + +* ⚠️ [FPDF.rotate()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.rotate) can produce malformed PDFs: use [FPDF.rotation()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.rotation) instead +* [FPDF.set_doc_option()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_doc_option): simply set the `.core_fonts_encoding` property as a replacement +* [FPDF.dashed_line()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.dashed_line): use [FPDF.set_dash_pattern()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_dash_pattern) and the normal drawing operations instead +* the `font_cache_dir` parameter of [FPDF() constructor](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF), that is currently ignored +* the `uni` parameter of [FPDF.add_font()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_font), that is currently ignored: if the value of the `fname` argument passed to `add_font()` ends with `.ttf`, it is considered a TrueType font +* the `type` parameter of [FPDF.image()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.image), that is currently ignored +* the `dest` parameter of [FPDF.output()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.output), that is currently ignored +* the `ln` parameter of [FPDF.multi_cell()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell): use `new_x=` & `new_y=` instead +* the `split_only` parameter of [FPDF.multi_cell()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell): use `dry_run=True` and `output="LINES"` instead +* the [HTMLMixin class](https://py-pdf.github.io/fpdf2/fpdf/html.html#fpdf.html.HTMLMixin): you can now directly use the [FPDF.write_html()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html) method +* the `infile` parametyer of [Template() constructor](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template), that is currently ignored +* the parameters `x/y/w/h` of `code39` elements provided to the [`Template` system](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template): please use `x1/y1/y2/size` instead +* the `dest` parameter of [Template.render()](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template.render), that is currently ignored + +Note that `DeprecationWarning` messages are not displayed by Python by default. +To get warned about deprecated features used in your code, you must execute your scripts with the `-Wd` option (_cf._ [documentation](https://docs.python.org/3/using/cmdline.html#cmdoption-W)), or enable them programmatically with `warnings.simplefilter('default', DeprecationWarning)`. diff --git a/docs/index.md b/docs/index.md index e02925fe2..b6f708488 100644 --- a/docs/index.md +++ b/docs/index.md @@ -99,6 +99,7 @@ or [open a discussion](https://github.com/py-pdf/fpdf2/discussions). ### They use fpdf2 ### +* **Harvard University** uses `fpdf2` in their [CS50 introductory class](https://cs50.harvard.edu/python/2022/psets/8/shirtificate/) * [Undying Dusk](https://lucas-c.itch.io/undying-dusk) : a **video game in PDF format**, with a gameplay based on exploration and logic puzzles, in the tradition of dungeon crawlers * [OpenDroneMap](https://github.com/OpenDroneMap/ODM) : a command line toolkit for processing aerial drone imagery * [OpenSfM](https://github.com/mapillary/OpenSfM) : a Structure from Motion library, serving as a processing pipeline for reconstructing camera poses and 3D scenes from multiple images diff --git a/fpdf/fpdf.py b/fpdf/fpdf.py index 39d813194..11482d1e6 100644 --- a/fpdf/fpdf.py +++ b/fpdf/fpdf.py @@ -1193,15 +1193,12 @@ def set_dash_pattern(self, dash=0, gap=0, phase=0): Set the current dash pattern for lines and curves. Args: - dash (float >= 0): - The length of the dashes in current units. + dash (float >= 0): The length of the dashes in current units. - gap (float >= 0): - The length of the gaps between dashes in current units. + gap (float >= 0): The length of the gaps between dashes in current units. If omitted, the dash length will be used. - phase (float >= 0): - Where in the sequence to start drawing. + phase (float >= 0): Where in the sequence to start drawing. Omitting 'dash' (= 0) resets the pattern to a solid line. """ @@ -1337,7 +1334,6 @@ def rect(self, x, y, w, h, style=None, round_corners=False, corner_radius=0): y (float): Ordinate of upper-left bounding box. w (float): Width. h (float): Height. - style (fpdf.enums.RenderStyle, str): Optional style of rendering. Possible values are: * `D` or empty string: draw border. This is the default value. diff --git a/fpdf/html.py b/fpdf/html.py index a57bf8b44..07026bd8c 100644 --- a/fpdf/html.py +++ b/fpdf/html.py @@ -720,6 +720,11 @@ def whitespace_repl(matchobj): class HTMLMixin: + """ + [**DEPRECATED since v2.6.0**] + You can now directly use the `FPDF.write_html()` method + """ + def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) warnings.warn( diff --git a/fpdf/template.py b/fpdf/template.py index a66b162c5..331b5a0fe 100644 --- a/fpdf/template.py +++ b/fpdf/template.py @@ -32,13 +32,9 @@ class FlexTemplate: def __init__(self, pdf, elements=None): """ - Arguments: - - pdf (fpdf.FPDF() instance): - All content will be added to this object. + Arguments: pdf (fpdf.FPDF() instance): All content will be added to this object. - elements (list of dicts): - A template definition in a list of dicts. + elements (list of dicts): A template definition in a list of dicts. If you omit this, then you need to call either load_elements() or parse_csv() before doing anything else. """ @@ -66,8 +62,7 @@ def load_elements(self, elements): Arguments: - elements (list of dicts): - A template definition in a list of dicts + elements (list of dicts): A template definition in a list of dicts """ key_config = { # key: type @@ -158,21 +153,16 @@ def parse_csv(self, infile, delimiter=",", decimal_sep=".", encoding=None): Arguments: - infile (string): - The filename of the CSV file. + infile (string): The filename of the CSV file. - delimiter (single character): - The character that seperates the fields in the CSV file: + delimiter (single character): The character that seperates the fields in the CSV file: Usually a comma, semicolon, or tab. - decimal_sep (single character): - The decimal separator used in the file. + decimal_sep (single character): The decimal separator used in the file. Usually either a point or a comma. - encoding (string): - The character encoding of the file. + encoding (string): The character encoding of the file. Default is the system default encoding. - """ def _varsep_float(s, default="0"): @@ -269,11 +259,9 @@ def split_multicell(self, text, element_name): Arguments: - text (string): - The input text string. + text (string): The input text string. - element_name (string): - The name of the template element to fit the text inside. + element_name (string): The name of the template element to fit the text inside. Returns: A list of substrings, each of which will fit into the element width @@ -539,14 +527,11 @@ def render(self, offsetx=0.0, offsety=0.0, rotate=0.0, scale=1.0): Arguments: - offsetx, offsety (float): - Place the template to move its origin to the given coordinates. + offsetx, offsety (float): Place the template to move its origin to the given coordinates. - rotate (float): - Rotate the inserted template around its (offset) origin. + rotate (float): Rotate the inserted template around its (offset) origin. - scale (float): - Scale the inserted template by this factor. + scale (float): Scale the inserted template by this factor. """ sorted_elements = sorted(self.elements, key=lambda x: x["priority"]) with self.pdf.local_context(): @@ -607,23 +592,18 @@ def __init__( """ Arguments: - infile (str): - [**DEPRECATED since 2.2.0**] unused, will be removed in a later version + infile (str): [**DEPRECATED since 2.2.0**] unused, will be removed in a later version - elements (list of dicts): - A template definition in a list of dicts. + elements (list of dicts): A template definition in a list of dicts. If you omit this, then you need to call either load_elements() or parse_csv() before doing anything else. - format (str): - The page format of the document (eg. "A4" or "letter"). + format (str): The page format of the document (eg. "A4" or "letter"). - orientation (str): - The orientation of the document. + orientation (str): The orientation of the document. Possible values are "portrait"/"P" or "landscape"/"L" - unit (str): - The units used in the template definition. + unit (str): The units used in the template definition. One of "mm", "cm", "in", "pt", or a number for points per unit. title (str): The title of the document. @@ -674,12 +654,10 @@ def render(self, outfile=None, dest=None): Arguments: - outfile (str): - If given, the PDF file will be written to this file name. + outfile (str): If given, the PDF file will be written to this file name. Alternatively, the `.pdf.output()` method can be manually called. - dest (str): - [**DEPRECATED since 2.2.0**] unused, will be removed in a later version. + dest (str): [**DEPRECATED since 2.2.0**] unused, will be removed in a later version. """ if dest: warnings.warn( diff --git a/mkdocs.yml b/mkdocs.yml index 0fb906c75..26e50a185 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,8 +51,7 @@ markdown_extensions: plugins: - search - include-markdown - # Disabled while waiting for resolution of https://github.com/greenape/mknotebooks/issues/1100 - # - mknotebooks + - mknotebooks - minify: minify_html: true - redirects: