🪜 Multiline text, spec compliance, friendlier API

CHANGELOG.rst

@@ -1,20 +1,41 @@
 Changelog
 =========
 
+0.3.0 (2022-12-02)
+------------------
+
+**Added**
+
+- 🍰 Documents can be created directly from string input
+- 🪜 Support for explicit newlines in text
+- 📢 ``Document.write()`` supports paths, file-like objects and iterator output
+- ✅ Improved PDF spec compliance
+
+**Changed**
+
+- 📚 Text is now positioned automatically within a page
+
 0.2.0 (2022-12-01)
 ------------------
 
+**Added**
+
 - 🖌️ Different builtin fonts can be selected
 - 📥 Truetype fonts can be embedded
+- 🌏 Support for non-ASCII text
 - 📐 Pages can be rotated
 - 🤏 Compression is applied to keep filesize small
 
 0.1.0 (2022-11-02)
 ------------------
 
-- 💬 Support basic ASCII text! on different pages!
+**Added**
+
+- 💬 Support basic ASCII text on different pages
 
 0.0.1 (2022-10-28)
 ------------------
 
-- 🌱 Initial release
+**Added**
+
+- 🌱 Write a valid, minimal, empty PDF file

Makefile

@@ -41,3 +41,8 @@ test: check pytest
 docs:
 	@touch docs/api.rst
 	make -C docs/ html
+
+publish:
+	rm -rf dist/*
+	poetry build
+	twine upload dist/*

README.rst

@@ -1,5 +1,5 @@
-🖍 PDFje
-========
+🖍 pdf'je
+=========
 
 .. image:: https://img.shields.io/pypi/v/pdfje.svg?style=flat-square
    :target: https://pypi.python.org/pypi/pdfje
@@ -18,46 +18,87 @@
 
 -----
 
-  **PDF·je** [PDF·yuh] *(noun)* Dutch for 'small PDF'
+  **pdf·je** [`🔉 <https://upload.wikimedia.org/wikipedia/commons/a/ac/Nl-pdf%27je.ogg>`_ PDF·yuh] (noun) Dutch for 'small PDF'
 
 Tiny library for writing simple PDFs.
 
 Currently under development.
 The API may change significantly until the 1.x release.
 Leave a ⭐️ on GitHub if you're interested how this develops!
 
-Why?
-----
+💁‍♂️ Why?
+----------
 
 The most popular Python libraries for writing PDFs are quite old
-and inspired by Java and PHP. **PDFje** is a modern, Pythonic library with
+and inspired by Java and PHP. **pdf'je** is a modern, Pythonic library with
 a more declarative API.
 
-How does it work?
------------------
+🚀 How does it work?
+--------------------
+
+Getting text on paper is super easy:
+
+.. code-block:: python
+
+  from pdfje import Document
+  Document("Olá Mundo!").write('hello.pdf')
+
+but you can of course do more:
 
 .. code-block:: python
 
-  >>> from pdfje import Document, Page, Text
-  >>> Document([
-  ...     Page([Text("Hello", at=(200, 700)), Text("World", at=(300, 670))]),
-  ...     Page(),
-  ...     Page([Text("This is the last page!", at=(300, 600))]),
-  ... ]).to_path('hello.pdf')
+  from pdfje import Page, Text, Font
+
+  myfont = Font.from_path('path/to/MyFont.ttf')
+  Document([
+      Page("""Simple is better than complex.
+              Complex is better than complicated."""),
+      Page(),
+      Page(Text("This text is bigger and fancier!", font=myfont, size=20))
+  ]).write('hello.pdf')
+
 
 See `the docs <https://pdfje.rtfd.io>`_ for a complete overview.
 
-Installation
-------------
+👩‍⚕️ Is pdf'je right for me?
+------------------------------
+
+Try it if you:
+
+- 🎯 Just want to get simple text into a PDF quickly
+- 🪄 Prefer coding in a declarative and Pythonic style
+- 🎁 Are looking for a lightweight, permissively licensed library
+- 🔭 Enjoy experimenting and contributing to something new
+
+Look elsewhere if you:
+
+- 🕸️ Want to turn HTML into PDF -- use ``wkhtmltopdf`` instead
+- 🔬 Need perfectly typeset documents -- use LaTeX instead
+- 🚚 Want lots of features -- use ``reportlab`` or ``fpdf2`` instead
+- ✂️  Need to parse or edit -- use ``PyPDF2`` or ``pdfsyntax`` instead
+
+🥘 So, what's cooking?
+----------------------
+
+The following features are planned:
+
+- 📑 Automatic line/page breaks
+- 🎨 ``rich``-inspired styles and inline markup
+- 🖼️ Support for images
+- ✏️  Basic drawing operations
+- 🔗 Bookmarks and links
+
+🎁 Installation
+---------------
 
 It's available on PyPI.
 
 .. code-block:: bash
 
   pip install pdfje
 
-Development
------------
+🛠️ Development
+--------------
 
 - Install dependencies with ``poetry install``.
 - To write output files during tests, use ``pytest --output-path=<outpur-dir>``

docs/guide.rst

@@ -7,14 +7,24 @@ Documents and pages
 PDF documents consist of pages, which may have graphical context (e.g. text).
 Below shows an example of creating a document and writing it to a file.
 
+You can pass in strings directly to use the default style,
+or use :class:`~pdfje.Text` to add style information.
+
 .. code-block:: python
 
-  >>> from pdfje import Document, Page, Text
-  >>> Document([
-  ...     Page([Text("Hello", at=(200, 700)), Text("World", at=(300, 670))]),
-  ...     Page(),  # empty page
-  ...     Page([Text("This is the last page!", at=(300, 600))]),
-  ... ]).to_path('hello.pdf')
+  from pdfje import Document, Page, Text
+  Document([
+      Page("Hello world!"),
+      Page(),  # empty page
+      Page(["here is", Text("BIG", size=40), "text"]),
+  ]).to_path('hello.pdf')
+
+
+Output targets
+--------------
+
+You can write to paths, files, file-like objects, or a stream.
+See :meth:`pdfje.Document.write` for details.
 
 
 Fonts and unicode
@@ -37,9 +47,9 @@ There are two types of fonts:
 
    .. code-block:: python
 
-      >>> from pdfje import Text, courier, helvetica
-      >>> Text("Hello Helvetica", font=helvetica)
-      >>> Text("Ciao, Courier", font=courier)
+      from pdfje import Text, courier, helvetica
+      Text("Hello Helvetica", font=helvetica)
+      Text("Ciao, Courier", font=courier)
 
    .. warning::
 
@@ -60,9 +70,9 @@ There are two types of fonts:
 
    .. code-block:: python
 
-      >>> from pdfje import Text, Font
-      >>> dejavu = Font.from_path("path/to/DejaVuSansCondensed.ttf")
-      >>> Text("We meet again, DejaVu!", font=dejavu)
+      from pdfje import Text, Font
+      dejavu = Font.from_path("path/to/DejaVuSansCondensed.ttf")
+      Text("We meet again, DejaVu!", font=dejavu)
 
    .. note::
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pdfje"
-version = "0.2.0"
+version = "0.3.0"
 description = "Tiny PDF writer"
 authors = ["Arie Bovenberg <[email protected]>"]
 license = "MIT"