diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api_reference.rst | 4 | ||||
| -rw-r--r-- | docs/changelog.rst | 323 | ||||
| -rw-r--r-- | docs/common_use_cases.rst | 89 | ||||
| -rw-r--r-- | docs/conf.py | 9 | ||||
| -rw-r--r-- | docs/contribute.rst | 7 | ||||
| -rw-r--r-- | docs/going_further.rst | 21 |
6 files changed, 432 insertions, 21 deletions
diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 80bf16c..0ceb6c5 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -7,13 +7,17 @@ API Reference :members: .. autoclass:: Dictionary + :show-inheritance: .. autoclass:: Stream :members: + :show-inheritance: .. autoclass:: String + :show-inheritance: .. autoclass:: Array + :show-inheritance: .. autoclass:: PDF :members: diff --git a/docs/changelog.rst b/docs/changelog.rst index acbf3c3..7afce9d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,6 +2,329 @@ Changelog ========= +Version 0.10.0 +------------- + +Released on 2024-04-29. + +New features: + +* Add standard compliant default identifier + +Contributors: + +* Guillaume Ayoub +* Wolfgang Walther + +Backers and sponsors: + +* Spacinov +* Kobalt +* Grip Angebotssoftware +* Manuel Barkhau +* SimonSoft +* Menutech +* KontextWork +* Simon Sapin +* René Fritz +* TrainingSparkle +* Healthchecks.io +* Docraptor +* Yanal-Yvez Fargialla +* Douwe van Loenen +* Morntag +* Xavid + + +Version 0.9.0 +------------- + +Released on 2024-02-26. + +Dependencies: + +* Python 3.12 is supported and tested +* Python 3.8+ is now needed, Python 3.7 is not supported anymore + +New features: + +* Add inline images support + +Performance: + +* Simplify `_to_bytes()` + +Documentation: + +* Add sample to create a PDF with metadata + +Contributors: + +* Panagiotis H.M. Issaris +* Guillaume Ayoub +* Lucie Anglade + +Backers and sponsors: + +* Spacinov +* Kobalt +* Grip Angebotssoftware +* Manuel Barkhau +* SimonSoft +* Menutech +* KontextWork +* René Fritz +* Simon Sapin +* Arcanite +* TrainingSparkle +* Healthchecks.io +* Hammerbacher +* Docraptor +* Yanal-Yvez Fargialla +* Morntag +* NBCO + + +Version 0.8.0 +------------- + +Released on 2023-09-25. + +New features: + +* Add text rise operator + +Backers and sponsors: + +* Spacinov +* Kobalt +* Grip Angebotssoftware +* Manuel Barkhau +* SimonSoft +* Menutech +* KontextWork +* NCC Group +* René Fritz +* Nicola Auchmuty +* Syslifters +* Hammerbacher +* TrainingSparkle +* Daniel Kucharski +* Healthchecks.io +* Yanal-Yvez Fargialla +* WakaTime +* Paheko +* Synapsium +* DocRaptor + + +Version 0.7.0 +------------- + +Released on 2023-07-03. + +Dependencies: + +* Python 3.11 is supported and tested + +Bug fixes: + +* Fix size of fields for xref + +Backers and sponsors: + +* Castedo Ellerman +* Spacinov +* Kobalt +* Grip Angebotssoftware +* Crisp BV +* Manuel Barkhau +* SimonSoft +* Menutech +* KontextWork +* NCC Group +* René Fritz +* TrainingSparkle +* Healthchecks.io +* Moritz Mahringer +* Yanal-Yvez Fargialla +* Synapsium +* Piotr Horzycki +* Hammerbacher + + +Version 0.6.0 +------------- + +Released on 2023-03-29. + +New features: + +* Add an option to use compressed object streams for PDF 1.5+, with financial support from Code & Co. +* Add new text operators +* Clean and fix documentation + +Backers and sponsors: + +* Kobalt +* Grip Angebotssoftware +* Spacinov +* Crisp BV +* Castedo Ellerman +* Manuel Barkhau +* SimonSoft +* Menutech +* KontextWork +* NCC Group +* René Fritz +* Moritz Mahringer +* Yanal-Yvez Fargialla +* Piotr Horzycki +* Healthchecks.io +* Hammerbacher +* TrainingSparkle +* Synapsium + + + +Version 0.5.0 +------------- + +Released on 2022-10-11. + +New features: + +* Add the PDF.page_references property +* Revert the PDF.pages['Kids'] behavior to be backwards compatible with version 0.3.0 + +Backers and sponsors: + +* Grip Angebotssoftware +* Manuel Barkhau +* Crisp BV +* SimonSoft +* Menutech +* Spacinov +* KontextWork +* René Fritz +* NCC Group +* Kobalt +* Tom Pohl +* John R Ellis +* Moritz Mahringer +* Yanal-Yvez Fargialla +* Gábor +* Piotr Horzycki +* Andrew Ittner + + +Version 0.4.0 +------------- + +Released on 2022-10-11. + +New features: + +* Allow nth page’s reference to be retrieved using PDF.pages['Kids'][n] + +Backers and sponsors: + +* Grip Angebotssoftware +* Manuel Barkhau +* Crisp BV +* SimonSoft +* Menutech +* Spacinov +* KontextWork +* René Fritz +* NCC Group +* Kobalt +* Tom Pohl +* John R Ellis +* Moritz Mahringer +* Yanal-Yvez Fargialla +* Gábor +* Piotr Horzycki +* Andrew Ittner + + +Version 0.3.0 +------------- + +Released on 2022-09-19. + +New features: + +* Support marked content +* Allow version and ID to be specified when initializing PDF objects + +Contributors: + +* Guillaume Ayoub + +Backers and sponsors: + +* Grip Angebotssoftware +* Manuel Barkhau +* Crisp BV +* SimonSoft +* Menutech +* Spacinov +* KontextWork +* René Fritz +* NCC Group +* Kobalt +* Tom Pohl +* John R Ellis +* Moritz Mahringer +* Gábor +* Piotr Horzycki +* Andrew Ittner + + +Version 0.2.0 +------------- + +Released on 2022-05-23. + +Dependencies: + +* Python 3.7+ is now needed, Python 3.6 is not supported anymore + +New features: + +* `d0be36b <https://github.com/CourtBouillon/pydyf/commit/d0be36b>`_: + Allow to set PDF version +* `879261c <https://github.com/CourtBouillon/pydyf/commit/879261c>`_: + Allow to set PDF identifier + +Contributors: + +* Guillaume Ayoub + +Backers and sponsors: + +* Grip Angebotssoftware +* Manuel Barkhau +* Crisp BV +* SimonSoft +* Menutech +* Spacinov +* KontextWork +* René Fritz +* Kobalt +* NCC Group +* Des images et des mots +* Nathalie Gutton +* Andreas Zettl +* Tom Pohl +* Moritz Mahringer +* Florian Demmer +* Yanal-Yvez Fargialla +* Gábor +* Piotr Horzycki + + Version 0.1.2 ------------- diff --git a/docs/common_use_cases.rst b/docs/common_use_cases.rst index 45e2d3d..d8343b3 100644 --- a/docs/common_use_cases.rst +++ b/docs/common_use_cases.rst @@ -97,7 +97,7 @@ Display image document = pydyf.PDF() - extra = Dictionary({ + extra = pydyf.Dictionary({ 'Type': '/XObject', 'Subtype': '/Image', 'Width': 197, @@ -158,9 +158,9 @@ Display text # And display it text = pydyf.Stream() text.begin_text() - text.set_font_size('F1', 24) + text.set_font_size('F1', 20) text.text_matrix(1, 0, 0, 1, 10, 90) - text.show_text(pydyf.String('Hello World')) + text.show_text(pydyf.String('Bœuf grillé & café'.encode('macroman'))) text.end_text() document.add_object(text) @@ -180,3 +180,86 @@ Display text with open('document.pdf', 'wb') as f: document.write(f) + +Add metadata +------------ + +.. code-block:: python + + import datetime + + import pydyf + + document = pydyf.PDF() + document.info['Author'] = pydyf.String('Jane Doe') + document.info['Creator'] = pydyf.String('pydyf') + document.info['Keywords'] = pydyf.String('some keywords') + document.info['Producer'] = pydyf.String('The producer') + document.info['Subject'] = pydyf.String('An example PDF') + document.info['Title'] = pydyf.String('A PDF containing metadata') + now = datetime.datetime.now() + document.info['CreationDate'] = pydyf.String(now.strftime('D:%Y%m%d%H%M%S')) + + document.add_page( + pydyf.Dictionary( + { + 'Type': '/Page', + 'Parent': document.pages.reference, + 'MediaBox': pydyf.Array([0, 0, 200, 200]), + } + ) + ) + + # 550 bytes PDF + with open('metadata.pdf', 'wb') as f: + document.write(f) + + +Display inline QR-code image +---------------------------- + +.. code-block:: python + + import pydyf + import qrcode + + # Create a QR code image + image = qrcode.make('Some data here') + raw_data = image.tobytes() + width = image.size[0] + height = image.size[1] + + document = pydyf.PDF() + stream = pydyf.Stream(compress=True) + stream.push_state() + x = 0 + y = 0 + stream.transform(width, 0, 0, height, x, y) + # Add the 1-bit grayscale image inline in the PDF + stream.inline_image(width, height, 'Gray', 1, raw_data) + stream.pop_state() + document.add_object(stream) + + # Put the image in the resources of the PDF + document.add_page( + pydyf.Dictionary( + { + 'Type': '/Page', + 'Parent': document.pages.reference, + 'MediaBox': pydyf.Array([0, 0, 400, 400]), + 'Resources': pydyf.Dictionary( + { + 'ProcSet': pydyf.Array( + ['/PDF', '/ImageB', '/ImageC', '/ImageI'] + ), + } + ), + 'Contents': stream.reference, + } + ) + ) + + # 909 bytes PDF + with open('qrcode.pdf', 'wb') as f: + document.write(f, compress=True) + diff --git a/docs/conf.py b/docs/conf.py index 585afd0..c868316 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,13 +1,7 @@ # pydyf documentation build configuration file. -import sys -from pathlib import Path - import pydyf -# Add current path for css_diagram_role -sys.path.append(str(Path(__file__).parent)) - # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ @@ -52,6 +46,9 @@ html_theme_options = { 'collapse_navigation': False, } +# Favicon URL +html_favicon = 'https://www.courtbouillon.org/static/images/favicon.png' + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/contribute.rst b/docs/contribute.rst index adf9024..d14e6b9 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -46,12 +46,17 @@ the pytest_ library. Launching tests require to have Ghostscript_ installed and available in ``PATH``. -You can launch tests (with code coverage and lint) using the following command:: +You can launch tests using the following command:: venv/bin/pytest +pydyf also uses ruff_ to check the coding style:: + + venv/bin/python -m ruff check + .. _pytest: https://docs.pytest.org/ .. _Ghostscript: https://www.ghostscript.com/ +.. _ruff: https://docs.astral.sh/ruff/ Documentation diff --git a/docs/going_further.rst b/docs/going_further.rst index ce9a8f3..c66f6c2 100644 --- a/docs/going_further.rst +++ b/docs/going_further.rst @@ -5,12 +5,11 @@ Going Further Why pydyf? ------------- -pydyf has been created to replace Cairo PDF generation in WeasyPrint_. +pydyf has been created to replace Cairo_ PDF generation in WeasyPrint_. -Indeed, there are some bugs in WeasyPrint caused by Cairo_ and Cairo has some -difficulties to make releases. -Also there are features which will be easier to implement while having more -control on the PDF generation. +Indeed, there were some bugs in WeasyPrint caused by Cairo, and new versions of +Cairo can take a long time to be released. There are also many features that +are easier to implement with more control on the PDF generation. So we created pydyf. @@ -20,13 +19,13 @@ So we created pydyf. Why Python? ----------- -Python is a really good language to design a small, OS-agnostic parser. As it -is object-oriented, it gives the possibility to follow the specification with -high-level classes and a small amount of very simple code. +Python is a really good language to design a small, OS-agnostic library. As it +is object-oriented, it gives the possibility to follow the PDF specification +with high-level classes and a small amount of very simple code. And of course, WeasyPrint is written in Python too, giving an obvious reason for this choice. -Speed is not pydyf’s main goal. Code simplicity, maintainability and -flexibility are more important goals for this library, as they give the -ability to stay really close to the specification and to fix bugs easily. +Speed is not pydyf’s main goal. Code simplicity, maintainability and +flexibility are more important goals for this library, as they give the ability +to stay really close to the specification and to fix bugs easily. |