Merge branch 'master' into issue-956

Author: TedBrookings

.gitignore

@@ -1,5 +1,6 @@
 # my files
 .env
+.DS_Store
 
 # codecov.io
 coverage.xml

CHANGELOG.md

@@ -21,6 +21,12 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 * [`FPDF.fonts.FontFace`](https://py-pdf.github.io/fpdf2/fpdf/fonts.html#fpdf.fonts.FontFace): Now has a static `combine` method that allows overriding a default FontFace (e.g. for specific cells in a table). Unspecified properties of the override FontFace retain the values of the default.
 ### Changed
 * [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): If cell styles are provided for cells in heading rows, combine the cell style as an override with the overall heading style.
+* SVG importing now supports clipping paths, and `defs` tags anywhere in the SVG file
+* [`TextColumns()`](https://py-pdf.github.io/fpdf2/TextColumns.html) can now have images inserted (both raster and vector).
+* [`TextColumns()`](https://py-pdf.github.io/fpdf2/TextColumns.html) can now advance to the next column with the new `new_column()` method or a FORM_FEED character (`\u000c`) in the text.
+### Fixed
+* Previously set dash patterns were not transferred correctly to new pages.
+* Inserted Vector images used to ignore the `keep_aspect_ratio` argument.
 
 ## [2.7.6] - 2023-10-11
 This release is the first performed from the [@py-pdf GitHub org](https://github.com/py-pdf), where `fpdf2` migrated.

docs/Development.md

@@ -70,6 +70,8 @@ pre-commit install
 To run tests, `cd` into `fpdf2` repository, install the dependencies using
 `pip install -r test/requirements.txt`,  and run `pytest`.
 
+You may also need to install [SWIG](https://swig.org/index.html) and [Ghostscript](https://www.ghostscript.com/).
+
 You can run a single test by executing: `pytest -k function_name`.
 
 Alternatively, you can use [Tox](https://tox.readthedocs.io/en/latest/).
@@ -116,9 +118,26 @@ All generated PDF files (including those processed by `qpdf`) will be stored in
 last test runs will be saved and then automatically deleted, so you can
 check the output in case of a failed test.
 
+### Generating PDF files for testing
 In order to generate a "reference" PDF file, simply call `assert_pdf_equal`
 once with `generate=True`.
 
+```
+import fpdf
+
+svg = fpdf.svg.SVGObject.from_file("path/to/file.svg")
+pdf = fpdf.FPDF(unit="pt", format=(svg.width, svg.height))
+pdf.add_page()
+svg.draw_to_page(pdf)
+
+assert_pdf_equal(
+    pdf,  
+    "path/for/pdf/output.pdf",
+    "path/for/pdf/",
+    generate=True
+)
+```
+
 ## Testing performances
 
 ### Code speed & profiling

docs/SVG.md

@@ -190,6 +190,8 @@ Additionally, `cairosvg` offers various options for optimizing the rendering per
 - stroke & fill coloring and opacity
 - basic stroke styling
 - Inline CSS styling via `style="..."` attributes.
+- clipping paths
+- `defs` tags anywhere in the SVG code
 
 ## Currently Unsupported Notable SVG Features ##
 

docs/TextColumns.md

@@ -7,12 +7,25 @@ _New in [:octicons-tag-24: 2.7.6](https://github.com/py-pdf/fpdf2/blob/master/CH
 
 The `FPDF.text_columns()` method allows to create columnar layouts, with one or several columns. Columns will always be of equal width.
 
+### Parameters ###
+
 Beyond the parameters common to all text regions, the following are available for text columns:
 
 * l_margin (float, optional) - override the current left page margin.
 * r_margin (float, optional) - override the current right page margin.
 * ncols (float, optional) - the number of columns to generate (Default: 2).
 * gutter (float, optional) - the horizontal space required between each two columns (Default 10).
+* balance (bool, optional) - Create height balanced columns, starting at the current height and ending at approximately the same level.
+
+### Methods ###
+
+Text columns support all the standard text region methods like `.paragraph()`, `.write()`, `.ln()`, and `.render()`. In addition to that:
+
+* `.new_column()` - End the current column and continue at the top of the next one.
+
+A FORM_FEED character (`\u000c`) in the text will have the same effect as an explicit call to `.new_column()`,
+
+Note that when used within balanced columns, switching to a new column manually will result in incorrect balancing.
 
 
 #### Single-Column Example ####
@@ -85,7 +98,7 @@ with cols:
 ```
 ![Balanced Columns](tcols-balanced.png)
 
-Note that column balancing only works reliably when the font size (specifically the line height) doesn't change. If parts of the text use a larger or smaller font than the rest, then the balancing will usually be out of whack. Contributions for a more refined balancing algorithm are welcome.
+Note that column balancing only works reliably when the font size (specifically the line height) doesn't change, and if there are no images included. If parts of the text use a larger or smaller font than the rest, then the balancing will usually be out of whack. Contributions for a more refined balancing algorithm are welcome.
 
 
 ### Possible future extensions

docs/TextRegion.md

@@ -44,12 +44,12 @@ The horizontal start position will be either at the current x position, if that
 In both horizontal and vertical positioning, regions with multiple columns may follow additional rules and restrictions.
 
 
-### Interaction between Regions ###
+### Interaction Between Regions ###
 
 Several region instances can exist at the same time. But only one of them can act as context manager at any given time. It is not currently possible to activate them recursively. But it is possible to use them intermittingly. This will probably most often make sense between a columnar region and a table or a graphic. You may have some running text ending at a given height, then insert a table/graphic, and finally continue the running text at the new height below the table within the existing column(s).
 
 
-### Common parameters ###
+### Common Parameters ###
 
 All types of text regions have the following constructor parameters in common:
 
@@ -59,14 +59,17 @@ All types of text regions have the following constructor parameters in common:
 * print_sh (bool, optional) - Treat a soft-hyphen (\\u00ad) as a printable character, instead of a line breaking opportunity. (Default: False)
 * skip_leading_spaces (default: False) - This flag is primarily used by `write_html()`, but may also have other uses. It removes all space characters at the beginning of each line.
 * wrapmode (default "WORD") - 
+* image (str or PIL.Image.Image or io.BytesIO, optional) - An image to add to the region. This is a convenience parameter for cases when no further text or images need to be added to the paragraph. If both "text" and "image" arguments are present, the text will be inserted first. (Default: None)
+* image_fill_width (bool, optional) - Indicates whether to increase the size of the image to fill the width of the column. Larger images will always be reduced to column width. (Default: False)
 
 All of those values can be overriden for each individual paragraph.
 
 
-### Common methods ###
+### Common Methods ###
 
-* `.paragraph()` [see characteristics parameters below] - establish a new paragraph in the text. The text added to this paragraph will start on a new line.
+* `.paragraph()` [see characteristic parameters below] - establish a new paragraph in the text. The text added to this paragraph will start on a new line.
 * `.write(text: str, link: = None)` - write text to the region. This is only permitted when no explicit paragraph is currently active.
+* `.image()` [see characteristic parameters below] - insert a vector or raster image in the region, flowing with the text like a paragraph.
 * `.ln(h: float = None)` - Start a new line moving either by the current font height or by the parameter "h". Only permitted when no explicit paragraph is currently active.
 * `.render()` - if the region is not used as a context manager with "with", this method must be called to actually process the added text.
 
@@ -87,9 +90,20 @@ For more typographical control, you can use the following arguments. Most of tho
 Other than text regions, paragraphs should always be used as context managers and never be reused. Violating those rules may result in the entered text turning up on the page out of sequence.
 
 
-### Possible future extensions
+### Possible Future Extensions ###
 
 Those features are currently not supported, but Pull Requests are welcome to implement them:
 
 * per-paragraph indentation
 * first-line indentation
+
+
+## Images ##
+
+_New in [:octicons-tag-24: 2.7.7](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md)_
+
+Most arguments for inserting images into text regions are the same as for the `FPDF.image()` method, and have the same or equivalent meaning.
+Since the image will be placed automatically, the "x" and "y" parameters are not available. The positioning can be controlled with "align", where the default is "LEFT", with the alternatives "RIGHT" and "CENTER".
+If neither width nor height are specified, the image will be inserted with the size resulting from the PDF default resolution of 72 dpi. If the "fill_width" parameter is set to True, it increases the size to fill the full column width if necessary. If the image is wider than the column width, it will always be reduced in size proportionally.
+The "top_margin" and "bottom_margin" parameters have the same effect as with text paragraphs.
+

docs/Tutorial-es.md

@@ -155,29 +155,30 @@ Este ejemplo es una variante del anterior, mostrando cómo poner el texto en mú
 
 [Texto de Julio Verne](https://github.com/py-pdf/fpdf2/raw/master/tutorial/20k_c1.txt)
 
-_⚠️ This section has changed a lot and requires a new translation: <https://github.com/py-pdf/fpdf2/issues/267>_
-
-English versions:
-
-* [Tuto 4 - Multi Columns](https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-4-multi-columns)
-* [Documentation on TextColumns](https://py-pdf.github.io/fpdf2/TextColumns.html
+La diferencia clave respecto al tutorial anterior es el uso del 
+método [`text_columns`](fpdf/fpdf.html#fpdf.fpdf.FPDF.text_column). 
+Este recoge todo el texto, posiblemente en incrementos, y lo distribuye entre el número de columnas solicitadas, insertando automáticamente saltos de página según sea necesario. Nota que mientras la instancia de `TextColumns` está activa como gestor de contexto, los estilos de texto y otras propiedades de la fuente pueden cambiarse. Estos cambios estarán contenidos en el contexto. Una vez se cierre, la configuración previa será reestablecida.
 
 
 ## Tutorial 5 - Creando tablas ##
 
+Este tutorial explicará cómo crear dos tablas diferentes,
+ para demostrar lo que se puede lograr con algunos ajustes simples.
+
 ```python
 {% include "../tutorial/tuto5.py" %}
 ```
 
 [PDF resultante](https://github.com/py-pdf/fpdf2/raw/master/tutorial/tuto5.pdf) -
 [Archivo de texto con países](https://github.com/py-pdf/fpdf2/raw/master/tutorial/countries.txt)
 
-_⚠️ This section has changed a lot and requires a new translation: <https://github.com/py-pdf/fpdf2/issues/267>_
-
-English versions:
+El primer ejemplo es alcanzado de la forma más básica posible, alimentando datos a [`FPDF.table()`](https://py-pdf.github.io/fpdf2/Tables.html). El resultado es rudimentario pero muy rápido de obtener.
 
-* [Tuto 5 - Creating Tables](https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-5-creating-tables)
-* [Documentation on tables](https://py-pdf.github.io/fpdf2/Tables.html)
+La segunda tabla trae algunas mejoras: colores, ancho de tabla limitado, altura de línea reducida,
+ títulos centrados, columnas con anchos personalizados, figuras alineadas a la derecha...
+ Aún más, las líneas horizontales han sido removidas.
+ Esto se hizo escogiendo un `borders_layout` entre los valores disponibles:
+ [`TableBordersLayout`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.TableBordersLayout).
 
 ## Tutorial 6 - Creando enlaces y combinando estilos de texto ##