Merge branch 'tables' of github.com:afriedman412/fpdf2 into tables

Author: afriedman412

.all-contributorsrc

@@ -994,6 +994,24 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "rakesh-nj",
+      "name": "Rakesh N J",
+      "avatar_url": "https://avatars.githubusercontent.com/u/121295004?v=4",
+      "profile": "https://github.com/rakesh-nj",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Iamrodos",
+      "name": "rodos",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4513819?v=4",
+      "profile": "https://github.com/Iamrodos",
+      "contributions": [
+        "bug"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.gitignore

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

CHANGELOG.md

@@ -17,8 +17,10 @@ in order to get warned about deprecated features used in your code.
 This can also be enabled programmatically with `warnings.simplefilter('default', DeprecationWarning)`.
 
 ## [2.7.7] - Not released yet
-• Tables can now handle multi-index formatting similar to how multi-column formatted is currently implemented.
-• Code added to format multi-index and multi-header to match Pandas (repeat labels are now omitted but spaced correctly)
+### Added
+* SVG importing now supports clipping paths, and `defs` tags anywhere in the SVG file
+* Tables can now handle multi-index formatting similar to how multi-column formatted is currently implemented.
+* Code added to format multi-index and multi-header to match Pandas (repeat labels are now omitted but spaced correctly)
 
 
 ## [2.7.6] - 2023-10-11

README.md

@@ -29,7 +29,7 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font('helvetica', size=12)
-pdf.cell(txt="hello world")
+pdf.cell(text="hello world")
 pdf.output("hello_world.pdf")
 ```
 
@@ -254,6 +254,8 @@ This library could only exist thanks to the dedication of many volunteers around
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/SandraFer"><img src="https://avatars.githubusercontent.com/u/50599578?v=4?s=100" width="100px;" alt="Sandra"/><br /><sub><b>Sandra</b></sub></a><br /><a href="#ideas-SandraFer" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/py-pdf/fpdf2/commits?author=SandraFer" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/navitho"><img src="https://avatars.githubusercontent.com/u/48886097?v=4?s=100" width="100px;" alt="navitho"/><br /><sub><b>navitho</b></sub></a><br /><a href="https://github.com/py-pdf/fpdf2/issues?q=author%3Anavitho" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/SaiHarshaK"><img src="https://avatars.githubusercontent.com/u/30663807?v=4?s=100" width="100px;" alt="Sai Harsha Kottapalli"/><br /><sub><b>Sai Harsha Kottapalli</b></sub></a><br /><a href="https://github.com/py-pdf/fpdf2/commits?author=SaiHarshaK" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/rakesh-nj"><img src="https://avatars.githubusercontent.com/u/121295004?v=4?s=100" width="100px;" alt="Rakesh N J"/><br /><sub><b>Rakesh N J</b></sub></a><br /><a href="https://github.com/py-pdf/fpdf2/commits?author=rakesh-nj" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Iamrodos"><img src="https://avatars.githubusercontent.com/u/4513819?v=4?s=100" width="100px;" alt="rodos"/><br /><sub><b>rodos</b></sub></a><br /><a href="https://github.com/py-pdf/fpdf2/issues?q=author%3AIamrodos" title="Bug reports">🐛</a></td>
     </tr>
   </tbody>
 </table>

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/Tutorial-bn.md

@@ -144,16 +144,13 @@ author ([set_author](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_author)) মেথড।
 
 [Jules Verne text](https://github.com/py-pdf/fpdf2/raw/master/tutorial/20k_c1.txt)
 
-পূর্বের টিউটরিয়ালের সাথে এর মূল পার্থক্য হলো 
-[accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) এবং the set_col মেথডের ব্যবহার।
+_⚠️ This section has changed a lot and requires a new translation: <https://github.com/py-pdf/fpdf2/issues/267>_
 
-[accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) মেথড ব্যবহার করে, যদি cell পৃষ্ঠার বর্তমান
- সর্বনিম্ন লিমিট পার করে, এই মেথড তখন বর্তমান কলাম নাম্বার চেক করে। যখন তা ২ এর ছোট হয় (আমরা একটি পৃষ্ঠাকে তিনটি 
- কলামে ভাগ করেছি), তখন set_col মেথডটি কল হয়, কলাম নাম্বার বেড়ে যায় এবং লিখার অবস্থান পরবর্তী কলামে চলে যায় যাতে 
- করে লিখা সেখানেই চলমান থাকে। 
+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
 
-যখন ৩য় কলামের সর্বনিম্ন লিমিটে পৌছায়, [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) মেথডটি 
-রিসেট হয় এবং একটি পেজ ব্রেক এপ্লাই করে আবার প্রথম কলামে চলে যায়। 
 
 ## টিউটোরিয়াল ৫ - টেবিল তৈরি করা ##
 

docs/Tutorial-de.md

@@ -145,14 +145,12 @@ Der Hauptunterschied zur vorherigen Lektion ist die Verwendung der Methode
 ```
 
 [Erzeugtes PDF](https://github.com/py-pdf/fpdf2/raw/master/tutorial/tuto5.pdf) -
-[Länder](https://github.com/py-pdf/fpdf2/raw/master/tutorial/countries.txt)
+[Länderdaten](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>_
+Das erste Beispiel wird auf die einfachst mögliche Weise umgesetzt, und einfach nur die Daten in die Tabelle eingefügt. Das Ergebnis ist eine sehr schlichte Darstellung, kann aber sehr schnell erzeugt werden.
 
-English versions:
+Die zweite Tabelle bringt einige Verfeinerungen: Farben, reduzierte Gesamtbreite, geringere Zeilenhöhe, zentrierter Text, individuelle Spaltenbreiten und rechts justierte Zahlenwerte. Zusätzliche wurden die horizontalen Linien ausgeblendet. Dies wird dadurch erreicht, dass das Argument `borders_layout` einen geeigneten Wert des Enums  [`TableBordersLayout`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.TableBordersLayout) erhält.
 
-* [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)
 
 ## Lektion 6 - Links erstellen und Textstile mischen ##
 

docs/Tutorial-es.md

@@ -155,33 +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)
 
-La diferencia clave con el tutorial anterior es el uso de los métodos 
-[accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) y set_col.
+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.
 
-Utilizando el método [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break), una vez 
-la celda cruce el límite inferior de la página, éste comprobará el número de la columna actual. Si 
-es menor que 2 (decidimos dividir la página en tres columnas) éste invocará al método set_col, 
-incrementando el número de columna y alterando la posición de la siguiente columna tal que el texto pueda continuar aquí.
-
-Una vez el límite inferior de la tercera columna es alcanzado, el 
-método [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) se reiniciará y 
-volverá a la primera columna, desencadenando un salto de página.
 
 ## 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 ##
 

docs/Tutorial-fr.md

@@ -103,11 +103,13 @@ Cet exemple est une variante du précédent qui montre comment répartir le text
 
 [Extrait de Jules Verne](https://github.com/py-pdf/fpdf2/raw/master/tutorial/20k_c1.txt)
 
-La principale différence avec le tutoriel précédent est l'utilisation des méthodes [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) et `set_col()`.
+_⚠️ This section has changed a lot and requires a new translation: <https://github.com/py-pdf/fpdf2/issues/267>_
 
-En utilisant la méthode [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break), une fois que la cellule franchit la limite inférieure de la page, elle vérifie le numéro de la colonne actuelle. Si celui-ci est inférieur à 2 (nous avons choisi de diviser la page en trois colonnes), il appelle la méthode `set_col()`, en augmentant le numéro de la colonne et en modifiant la position de la colonne suivante pour que le texte puisse s'y poursuivre.
+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
 
-Une fois que la limite inférieure de la troisième colonne est atteinte, la méthode [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) sera réinitialisée et retournera à la première colonne. Cela déclenchera un saut de page.
 
 ## Tuto 5 - Créer des tables ##
 Ce tutoriel explique comment créer facilement des tableaux. Deux tableaux différents sont générés, pour illustrer ce qui peut être produit avec de très simples changements.

docs/Tutorial-gr.md

@@ -101,11 +101,13 @@ pdf.cell(60, 10, 'Powered by FPDF.', new_x="LMARGIN", new_y="NEXT", align='C')
 
 [Κείμενο του Jules Verne](https://github.com/py-pdf/fpdf2/raw/master/tutorial/20k_c1.txt)
 
-Η κύρια διαφορά από το προηγούμενο παράδειγμα είναι η χρήση των μεθόδων [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) και set_col.
+_⚠️ This section has changed a lot and requires a new translation: <https://github.com/py-pdf/fpdf2/issues/267>_
+
+English versions:
 
-Χρησιμοποιώντας την μέθοδο [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break), μόλις το κελί ξεπεράσει το κάτω όριο της σελίδας, γίνεται έλεγχος του αριθμού της τωρινής στήλης. Εάν ο αριθμός αυτός είναι μικρότερος του 2 (επιλέξαμε την κατανομή της σελίδας σε τρεις στήλες) θα κληθεί η μέθοδος set_col, αυξάνοντας τον αριθμό στήλης και αλλάζοντας την θέση της αμέσως επόμενης στήλης έτσι ώστε το κείμενο να συνεχιστεί εκεί.
+* [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
 
-Μόλις φτάσουμε στο το κάτω όριο σελίδας της τρίτης στήλης, η μέθοδος [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) επαναφέρεται και μεταφερόμαστε ξανά πίσω στην πρώτη στήλη όπου πραγματοποιείται αλλαγή σελίδας.
 
 ## Μάθημα 5 - Δημιουργία Πινάκων ##
 

docs/Tutorial-he.md

@@ -106,13 +106,31 @@ pdf.cell(60, 10, 'Powered by FPDF.', new_x="LMARGIN", new_y="NEXT", align='C')
 
 [Jules Verne text](https://github.com/py-pdf/fpdf2/raw/master/tutorial/20k_c1.txt)
 
-ההבדל העיקרי בין דוגמא זו לקודמת הוא השימוש במתודות [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) וset_col
+ההבדל העיקרי מהדוגמא הקודמת הוא השימוש במתודת ה
+[`text_columns`](fpdf/fpdf.html#fpdf.fpdf.FPDF.text_column). 
+היא אוספת את כל הטקסט, ומפזרת אותו על מספר העמודות המבוקש (לפעמים מגדילה אותו), ואוטומטית מעבירה עמוד כשצריך. שימו לב שבזמן שמופע של `TextColumns` פועל כמנהל הקשר (context manager), עיצוב של טקסט ואלמנטים נוספים עשויים להשתנות. שינויים אלה מוכלים בהקשר.
+ברגע שהמופע נסגר, ההגדרות הקודמות יוחלו שוב.
 
-ע"י שימוש במתודה [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break), ברגע שתא חורג מהגבול התחתון של הדף, המתודה בודקת את מספר העמודה הנוכחי. אם הוא קטן מ2 (בחרנו לחלק את הדף ל3 עמודות) תיקרא המתודה set_col, שמגדילה את מספר העמודה ומשנה את הפוזיציה של העמודה הבאה כך שהטקסט ימשיך בה.
+## 5 - יצירת טבלאות ##
+דוגמא זו מסבירה כיצד ניתן ליצור שתי טבלאותשונות, על מנת להדגים מה ניתן להשיג באמצעות התאמות קטנות.
+
+```python
+{% include "../tutorial/tuto5.py" %}
+```
+
+[תוצר](https://github.com/py-pdf/fpdf2/raw/master/tutorial/tuto5.pdf) -
+[Countries CSV data](https://github.com/py-pdf/fpdf2/raw/master/tutorial/countries.txt)
+
+את הטבלא הראשונה ניתן לייצר בדרך הפשוטה ביותר, על ידי הזנת דאטה [`FPDF.table()`](https://py-pdf.github.io/fpdf2/Tables.html).
+התוצאה היא בסיסית אבל קלה ומהירה.
+
+The second table brings some improvements: colors, limited table width, reduced line height,
+הטבלא השניה מציגה מספר שיפורים: צבעיםת רוחב טבא מוגבלת גובה קווים מופח, כותרות ממורכזות, רוחב עמודות מותאם אישית, יישור לימין...
+בנוסף, קווים אופקיים הוסרו.
+זה נעשה על ידי בחירת `borders_layout` עם הערכים הזמינים:
+ [`TableBordersLayout`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.TableBordersLayout).
 
-ברגע שהגענו לגבול התחתון של העמודה השלישית, המתודה [accept_page_break](fpdf/fpdf.html#fpdf.fpdf.FPDF.accept_page_break) תאותחל, תחזור לעמודה הראשונה ותיצור מעבר עמוד.
 
-## 5 - יצירת טבלאות ##
 
 ```python
 {% include "../tutorial/tuto5.py" %}
@@ -151,4 +169,4 @@ English versions:
 
 ניתן גם להשתמש במתודה `()write_html` כדי לשנות סגנונות גופן ולהוסיף קישורים. זהו פארסר של html, שמאפשר להוסיף טקסט, לשנות את הסגנון ולהוסיף קישורים באמצעות html.
 
-</div>
+</div>