Skip to main content

sampledoc

CI PyPI Python License: MPL 2.0

Small, localized, byte-for-byte reproducible sample office documents.

sampledoc writes a believable folder of documents - a quarterly report, a budget, a contract, an invoice, a contact list - in 15 languages and 9 file formats. It has no dependencies: every file is written by hand, a few kilobytes each, with no images and no third-party material.

It was built to give app-store screenshots of OpenDocument Reader (Android and iOS) a document in the language of each store listing, and is just as useful as test fixtures for anything that opens office files.

Install

pip install sampledoc
# or run it without installing
uvx sampledoc --list
pipx run sampledoc --list

Requires Python 3.10 or newer.

Command line

sampledoc -o samples/                      # everything: 9 samples x 15 languages
sampledoc -o samples/ -l de -l fr          # only German and French
sampledoc -o samples/ -s text -s paper     # only the .odt report and the .pdf invoice
sampledoc -o samples/ --locales locales.json   # also map device locales to languages
sampledoc --list                           # what languages and samples there are

Files are named sample-<sample>-<language>.<ext>, e.g. sample-text-de.odt.

Next to them it writes screenshot-names.json, which holds, per language, a realistic display name for every sample (plus a set of "filler" file names to pad out a folder view) and a word to search the report for that is guaranteed to appear in it several times:

{
 "languages": {
  "de": {
   "files": {"text": "Quartalsbericht", "sheet": "Budget", "paper": "Rechnung", "...": "..."},
   "search": "version"
  }
 },
 "locales": {"de-DE": "de"}
}

locales is only present when --locales FILE is given; the file is a JSON object mapping device/store locales to sample languages. Pass --no-names to skip the file.

Samples

Sample Format What it is
text .odt a quarterly report with headed sections and a table of costs, long enough to fill A4
sheet .ods a budget: 40 rows over six months, on two sheets
slides .odp a three slide project plan, 16:9
word .docx a service agreement with numbered clauses and an appendix
cells .xlsx a small table of sales figures
deck .pptx a single titled, bulleted slide
paper .pdf a two page invoice (Helvetica/WinAnsi - languages it cannot spell get the English invoice)
rows .csv a contact list
notes .txt the report and the slides as plain text

Languages: en, cs, de, es, et, fr, hi, it, ja, pl, pt-BR, ru, sv, tr, zh.

Python API

import sampledoc

sampledoc.languages()  # ('en', 'cs', 'de', ...)
sampledoc.SAMPLES  # {'text': Sample(extension='odt', ...), ...}

data = sampledoc.document("text", "de")  # bytes of sample-text-de.odt
sampledoc.generate("out/", languages=["en"], samples=["text", "paper"])  # -> [Path, ...]

sampledoc.file_names("de")  # {'text': 'Quartalsbericht', ...}
sampledoc.query("de")  # the word to search the report for
sampledoc.manifest({"de-DE": "de"})  # what goes into screenshot-names.json

Reproducibility

The same version of sampledoc always writes the same documents: zip entries carry a fixed 1980-01-01 timestamp, fixed permissions and a fixed creating system, and nothing depends on the clock, the platform or the locale. The compressed bytes inside .odt/.docx/... packages are byte-for-byte identical as long as Python uses the same zlib; Python 3.14 on Windows (and some Linux distributions) ship zlib-ng, which compresses the same contents differently.

The test suite pins a fingerprint of every file, so a change to the output is always a deliberate one - and is called out in the changelog, since it changes every screenshot taken of it.

If you need stable output across upgrades, pin the version.

Contributing

Adding or fixing a language is a matter of editing one JSON file in src/sampledoc/languages/. See CONTRIBUTING.md.

License

Mozilla Public License 2.0

Metadata

Release files for sampledoc 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sampledoc 0.1.0
File Size Uploaded Provenance Actions
sampledoc-0.1.0.tar.gz 65.6 kB With provenance Details for sampledoc-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sampledoc 0.1.0
File Interpreter ABI Platform Actions
sampledoc-0.1.0-py3-none-any.whl Python 3 none any Details for sampledoc-0.1.0-py3-none-any.whl

Total release size: 132.4 kB

Release files / sampledoc-0.1.0.tar.gz

Download URL sampledoc-0.1.0.tar.gz
Size 65.6 kB
Tags Source
SHA-256 checksum
How to use checksums
fc6e98c81bc7b1040de76f3e399bc71c31993eb0464f4a695d9c008b54f398d4
BLAKE2b-256 checksum
How to use checksums
2cb3773f83afd356ef5687856d3889637b9c1ba161b6ffbd665dc7ee9554bac4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / sampledoc-0.1.0-py3-none-any.whl

Download URL sampledoc-0.1.0-py3-none-any.whl
Size 66.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
59458078b25215b391e0d375ce17040547d8f1ddc619b161b5aeb8ab46e77409
BLAKE2b-256 checksum
How to use checksums
59953bf0944b9fd0f13ad0196e5432c7f6f893b6526f3b7ffaf185f299c255d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for sampledoc 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sampledoc-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page