🌷 pdfje
========
.. image:: https://img.shields.io/pypi/v/pdfje.svg?style=flat-square&color=blue
:target: https://pypi.python.org/pypi/pdfje
.. image:: https://img.shields.io/pypi/pyversions/pdfje.svg?style=flat-square
:target: https://pypi.python.org/pypi/pdfje
.. image:: https://img.shields.io/pypi/l/pdfje.svg?style=flat-square&color=blue
:target: https://pypi.python.org/pypi/pdfje
.. image:: https://img.shields.io/badge/mypy-strict-forestgreen?style=flat-square
:target: https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-strict
.. image:: https://img.shields.io/badge/coverage-99%25-forestgreen?style=flat-square
:target: https://github.com/ariebovenberg/pdfje
.. image:: https://img.shields.io/github/actions/workflow/status/ariebovenberg/pdfje/tests.yml?branch=main&style=flat-square
:target: https://github.com/ariebovenberg/pdfje
.. image:: https://img.shields.io/readthedocs/pdfje.svg?style=flat-square
:target: http://pdfje.readthedocs.io/
..
**pdf·je** [`🔉 <https://upload.wikimedia.org/wikipedia/commons/a/ac/Nl-pdf%27je.ogg>`_ PDF·yuh] (noun) Dutch for 'small PDF'
**Write beautiful PDFs in declarative Python.**
*(Currently in active development. Leave a* ⭐️ *on GitHub if you're interested how this develops!)*
Features
--------
What makes **pdfje** stand out from the other PDF writers? Here are some of the highlights:
🧩 Declarative API
~~~~~~~~~~~~~~~~~~
In most PDF writers, you create empty objects and
then mutate them with methods like ``addText()``,
all while changing the state with methods like ``setFont()``.
**Pdfje** is different. You describe the document you want to write,
and pdfje takes care of the details. No state to manage, no mutations.
This makes your code easier to reuse and reason about.
.. code-block:: python
from pdfje import Document
Document("Olá Mundo!").write("hello.pdf")
See `the tutorial <https://pdfje.rtfd.io/en/latest/tutorial.html>`_
for a complete overview of features, including:
- Styling text including font, size, and color
- Automatic layout of text into one or more columns
- Builtin and embedded fonts
- Drawing basic shapes
See the roadmap_ for supported features.
📖 Decent typography
~~~~~~~~~~~~~~~~~~~~
Legibility counts. Good typography is a key part of that.
**Pdfje** supports several features to make your documents look great:
- Visually pleasing linebreaks, using the `same basic principles as LaTeX <https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap#Knuth's_algorithm>`_
- Automatic `kerning <https://en.wikipedia.org/wiki/Kerning>`_ using available font metrics
- Avoiding `widows and orphans <https://en.wikipedia.org/wiki/Widows_and_orphans>`_ by moving
lines between columns or pages.
.. image:: https://github.com/ariebovenberg/pdfje/raw/main/sample.png
:alt: Sample document with two columns of text
🎈 Small footprint
~~~~~~~~~~~~~~~~~~
The PDF format supports many features, but most of the time you only need a few.
Why install many dependencies — just to write a simple document?
Not only is **pdfje** pure-Python, it allows you to
install only the dependencies you need.
.. code-block:: bash
pip install pdfje # no dependencies
pip install pdfje[fonts, hyphens] # embedded fonts and improved hyphenation
.. _roadmap:
Roadmap
-------
**Pdfje** is still in active development,
so it is not yet feature-complete.
Until the 1.0 version, the API may change with minor releases.
Features:
✅ = implemented, 🚧 = planned, ❌ = not planned
- Typesetting
- ✅ Automatic kerning
- ✅ Wrapping text into lines, columns, and pages
- ✅ Page sizes
- ✅ Centering text
- ✅ Justification
- ✅ Hyphenation
- ✅ Move lines between columns/pages to avoid widows/orphans
- ✅ Tex-style line breaking
- 🚧 Headings (which stick to their paragraphs)
- 🚧 Indentation
- 🚧 Keeping layout elements together
- 🚧 Loosening paragraphs to avoid orphans/widows
- 🚧 Broader unicode support in text wrapping
- Drawing operations
- ✅ Lines
- ✅ Rectangles
- ✅ Circles, ellipses
- 🚧 Arbitrary paths, fills, and strokes
- Text styling
- ✅ Font and size
- ✅ Embedded fonts
- ✅ Colors
- ✅ Bold, italic
- 🚧 Underline and strikethrough
- 🚧 Superscript and subscript
- ❌ Complex fill patterns
- 🚧 Images
- 🚧 Bookmarks and links
- 🚧 Tables
- 🚧 Bullet/numbered lists
- 🚧 Inline markup with Markdown (Commonmark/MyST)
- ❌ Emoji
- ❌ Tables of contents
- ❌ Forms
- ❌ Annotations
Versioning and compatibility policy
-----------------------------------
**Pdfje** follows semantic versioning.
Until the 1.0 version, the API may change with minor releases.
Breaking changes will be announced in the changelog.
Since the API is fully typed, your typechecker and/or IDE
will help you adjust to any API changes.
License
-------
This library is licensed under the terms of the MIT license.
It also includes short scripts from other projects (see ``pdfje/vendor``),
which are either also MIT licensed, or in the public domain.
Contributing
------------
Here are some useful tips for developing in the ``pdfje`` codebase itself:
- Install dependencies with ``poetry install``.
- To write output files during tests, use ``pytest --output-path=<outpur-dir>``
- To also run more comprehensive but 'slow' tests, use ``pytest --runslow``
Acknowledgements
----------------
**pdfje** is inspired by the following projects.
If you're looking for a PDF writer, you may want to check them out as well:
- `python-typesetting <https://github.com/brandon-rhodes/python-typesetting>`_
- `fpdf2 <https://pyfpdf.github.io/fpdf2/index.html>`_
- `ReportLab <https://www.reportlab.com/>`_
- `WeasyPrint <https://weasyprint.org/>`_
- `borb <httpsL//github.com/jorisschellekens/borb/>`_
- `wkhtmltopdf <https://wkhtmltopdf.org/>`_
- `pydyf <https://github.com/CourtBouillon/pydyf>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/ariebovenberg/pdfje",
"name": "pdfje",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0",
"maintainer_email": "",
"keywords": "pdf",
"author": "Arie Bovenberg",
"author_email": "a.c.bovenberg@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/87/02/fe255c018b96c6ae42b08ac635919990e679aa881fb2574e7dae90309e33/pdfje-0.6.1.tar.gz",
"platform": null,
"description": "\ud83c\udf37 pdfje\n========\n\n.. image:: https://img.shields.io/pypi/v/pdfje.svg?style=flat-square&color=blue\n :target: https://pypi.python.org/pypi/pdfje\n\n.. image:: https://img.shields.io/pypi/pyversions/pdfje.svg?style=flat-square\n :target: https://pypi.python.org/pypi/pdfje\n\n.. image:: https://img.shields.io/pypi/l/pdfje.svg?style=flat-square&color=blue\n :target: https://pypi.python.org/pypi/pdfje\n\n.. image:: https://img.shields.io/badge/mypy-strict-forestgreen?style=flat-square\n :target: https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-strict\n\n.. image:: https://img.shields.io/badge/coverage-99%25-forestgreen?style=flat-square\n :target: https://github.com/ariebovenberg/pdfje\n\n.. image:: https://img.shields.io/github/actions/workflow/status/ariebovenberg/pdfje/tests.yml?branch=main&style=flat-square\n :target: https://github.com/ariebovenberg/pdfje\n\n.. image:: https://img.shields.io/readthedocs/pdfje.svg?style=flat-square\n :target: http://pdfje.readthedocs.io/\n\n..\n\n **pdf\u00b7je** [`\ud83d\udd09 <https://upload.wikimedia.org/wikipedia/commons/a/ac/Nl-pdf%27je.ogg>`_ PDF\u00b7yuh] (noun) Dutch for 'small PDF'\n\n**Write beautiful PDFs in declarative Python.**\n\n*(Currently in active development. Leave a* \u2b50\ufe0f *on GitHub if you're interested how this develops!)*\n\nFeatures\n--------\n\nWhat makes **pdfje** stand out from the other PDF writers? Here are some of the highlights:\n\n\ud83e\udde9 Declarative API\n~~~~~~~~~~~~~~~~~~\n\nIn most PDF writers, you create empty objects and\nthen mutate them with methods like ``addText()``,\nall while changing the state with methods like ``setFont()``.\n**Pdfje** is different. You describe the document you want to write,\nand pdfje takes care of the details. No state to manage, no mutations.\nThis makes your code easier to reuse and reason about.\n\n.. code-block:: python\n\n from pdfje import Document\n Document(\"Ol\u00e1 Mundo!\").write(\"hello.pdf\")\n\nSee `the tutorial <https://pdfje.rtfd.io/en/latest/tutorial.html>`_\nfor a complete overview of features, including:\n\n- Styling text including font, size, and color\n- Automatic layout of text into one or more columns\n- Builtin and embedded fonts\n- Drawing basic shapes\n\nSee the roadmap_ for supported features.\n\n\ud83d\udcd6 Decent typography\n~~~~~~~~~~~~~~~~~~~~\n\nLegibility counts. Good typography is a key part of that.\n**Pdfje** supports several features to make your documents look great:\n\n- Visually pleasing linebreaks, using the `same basic principles as LaTeX <https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap#Knuth's_algorithm>`_\n- Automatic `kerning <https://en.wikipedia.org/wiki/Kerning>`_ using available font metrics\n- Avoiding `widows and orphans <https://en.wikipedia.org/wiki/Widows_and_orphans>`_ by moving\n lines between columns or pages.\n\n.. image:: https://github.com/ariebovenberg/pdfje/raw/main/sample.png\n :alt: Sample document with two columns of text\n\n\ud83c\udf88 Small footprint\n~~~~~~~~~~~~~~~~~~\n\nThe PDF format supports many features, but most of the time you only need a few.\nWhy install many dependencies \u2014 just to write a simple document?\nNot only is **pdfje** pure-Python, it allows you to\ninstall only the dependencies you need.\n\n.. code-block:: bash\n\n pip install pdfje # no dependencies\n pip install pdfje[fonts, hyphens] # embedded fonts and improved hyphenation\n\n.. _roadmap:\n\nRoadmap\n-------\n\n**Pdfje** is still in active development,\nso it is not yet feature-complete.\nUntil the 1.0 version, the API may change with minor releases.\n\nFeatures:\n\n\u2705 = implemented, \ud83d\udea7 = planned, \u274c = not planned\n\n- Typesetting\n - \u2705 Automatic kerning\n - \u2705 Wrapping text into lines, columns, and pages\n - \u2705 Page sizes\n - \u2705 Centering text\n - \u2705 Justification\n - \u2705 Hyphenation\n - \u2705 Move lines between columns/pages to avoid widows/orphans\n - \u2705 Tex-style line breaking\n - \ud83d\udea7 Headings (which stick to their paragraphs)\n - \ud83d\udea7 Indentation\n - \ud83d\udea7 Keeping layout elements together\n - \ud83d\udea7 Loosening paragraphs to avoid orphans/widows\n - \ud83d\udea7 Broader unicode support in text wrapping\n- Drawing operations\n - \u2705 Lines\n - \u2705 Rectangles\n - \u2705 Circles, ellipses\n - \ud83d\udea7 Arbitrary paths, fills, and strokes\n- Text styling\n - \u2705 Font and size\n - \u2705 Embedded fonts\n - \u2705 Colors\n - \u2705 Bold, italic\n - \ud83d\udea7 Underline and strikethrough\n - \ud83d\udea7 Superscript and subscript\n - \u274c Complex fill patterns\n- \ud83d\udea7 Images\n- \ud83d\udea7 Bookmarks and links\n- \ud83d\udea7 Tables\n- \ud83d\udea7 Bullet/numbered lists\n- \ud83d\udea7 Inline markup with Markdown (Commonmark/MyST)\n- \u274c Emoji\n- \u274c Tables of contents\n- \u274c Forms\n- \u274c Annotations\n\nVersioning and compatibility policy\n-----------------------------------\n\n**Pdfje** follows semantic versioning.\nUntil the 1.0 version, the API may change with minor releases.\nBreaking changes will be announced in the changelog.\nSince the API is fully typed, your typechecker and/or IDE\nwill help you adjust to any API changes.\n\nLicense\n-------\n\nThis library is licensed under the terms of the MIT license.\nIt also includes short scripts from other projects (see ``pdfje/vendor``),\nwhich are either also MIT licensed, or in the public domain.\n\nContributing\n------------\n\nHere are some useful tips for developing in the ``pdfje`` codebase itself:\n\n- Install dependencies with ``poetry install``.\n- To write output files during tests, use ``pytest --output-path=<outpur-dir>``\n- To also run more comprehensive but 'slow' tests, use ``pytest --runslow``\n\nAcknowledgements\n----------------\n\n**pdfje** is inspired by the following projects.\nIf you're looking for a PDF writer, you may want to check them out as well:\n\n- `python-typesetting <https://github.com/brandon-rhodes/python-typesetting>`_\n- `fpdf2 <https://pyfpdf.github.io/fpdf2/index.html>`_\n- `ReportLab <https://www.reportlab.com/>`_\n- `WeasyPrint <https://weasyprint.org/>`_\n- `borb <httpsL//github.com/jorisschellekens/borb/>`_\n- `wkhtmltopdf <https://wkhtmltopdf.org/>`_\n- `pydyf <https://github.com/CourtBouillon/pydyf>`_\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Write beautiful PDFs in declarative Python",
"version": "0.6.1",
"project_urls": {
"Documentation": "https://pdfje.readthedocs.io",
"Homepage": "https://github.com/ariebovenberg/pdfje",
"Repository": "https://github.com/ariebovenberg/pdfje"
},
"split_keywords": [
"pdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b095277c66b766b02b6f220819ffbc6283849ff3aac871b6bf593e01e9652a9",
"md5": "20b3b8099b48c35ee4d56a628529f068",
"sha256": "cf7220251aadee7c09b6d39d8abbc0928dcc7cc60a41aa13ce18aa970ff822ab"
},
"downloads": -1,
"filename": "pdfje-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20b3b8099b48c35ee4d56a628529f068",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0",
"size": 124193,
"upload_time": "2023-11-13T18:32:48",
"upload_time_iso_8601": "2023-11-13T18:32:48.535075Z",
"url": "https://files.pythonhosted.org/packages/2b/09/5277c66b766b02b6f220819ffbc6283849ff3aac871b6bf593e01e9652a9/pdfje-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8702fe255c018b96c6ae42b08ac635919990e679aa881fb2574e7dae90309e33",
"md5": "28f7c5c693aaf0d91229f82685fae7e1",
"sha256": "e4951ecebdccfb1d532c14ff9f74824bf3ea6cb638485a294ee8e9e0b1faa700"
},
"downloads": -1,
"filename": "pdfje-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "28f7c5c693aaf0d91229f82685fae7e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0",
"size": 111531,
"upload_time": "2023-11-13T18:32:50",
"upload_time_iso_8601": "2023-11-13T18:32:50.430189Z",
"url": "https://files.pythonhosted.org/packages/87/02/fe255c018b96c6ae42b08ac635919990e679aa881fb2574e7dae90309e33/pdfje-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-13 18:32:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ariebovenberg",
"github_project": "pdfje",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pdfje"
}
JSON
