brewdoc 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +49 -27
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -3,37 +3,46 @@
3
3
  [![PyPI](https://img.shields.io/pypi/v/brewdoc)](https://pypi.org/project/brewdoc/)
4
4
  [![CI](https://github.com/kochetkov-ma/brewdoc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kochetkov-ma/brewdoc/actions/workflows/ci.yml)
5
5
  [![Release](https://img.shields.io/github/v/release/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/releases/latest)
6
- [![MIT](https://img.shields.io/github/license/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/LICENSE)
6
+ [![MIT](https://img.shields.io/github/license/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/LICENSE)
7
7
 
8
8
  Fast, deterministic document-to-Markdown conversion for agent systems. Easy to install. No model weights, OCR or external services.
9
9
 
10
10
  Local conversion runs offline after installation, with no runtime component downloads.
11
11
  Supported documents become one Markdown file and a JSON receipt describing omissions.
12
- See [formats and limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/FORMATS.md).
12
+ See [formats and limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md).
13
+ Version 0.4.1 added [selected ZIP/XML reader budgets](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#zipxml-reader-limits)
14
+ for DOCX/PPTX and workbook metadata/artifacts. Excessive work refuses before output
15
+ writes; native workbook values and total process memory remain outside those bounds.
16
+
17
+ Version 0.5.0 adds ODT/ODP text and tables, selected MIME email bodies and exact UTF-8
18
+ Markdown/text pass-through. It preserves workbook Unicode and exposed datetime precision,
19
+ and selects one DOCX compatibility fallback.
20
+ It also adds textless PDF page facts and selected caption, table and math-spacing fixes.
21
+ See the [format contracts](FORMATS.md).
13
22
 
14
23
  ## Install
15
24
 
16
- These examples select 0.4.0. Use a channel listed as available in [that release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.4.0). Choose one method:
25
+ These examples select 0.5.0. Use a channel listed as available in [that release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.5.0). Choose one method:
17
26
 
18
27
  Article mode is introduced in 0.4.0. Channel availability is listed in the release.
19
28
 
20
29
  ```sh
21
- python -m pip install "brewdoc==0.4.0"
22
- uv tool install --python 3.12 "brewdoc==0.4.0"
23
- pipx install --python 3.12 "brewdoc==0.4.0"
30
+ python -m pip install "brewdoc==0.5.0"
31
+ uv tool install --python 3.12 "brewdoc==0.5.0"
32
+ pipx install --python 3.12 "brewdoc==0.5.0"
24
33
  ```
25
34
 
26
35
  Use a virtual environment for pip. Python 3.12+ is required; HTML/URL need CPython 3.12-3.14.
27
- [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/INSTALL.md) covers prerequisites, Windows, uvx, PATH, update and removal.
36
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/INSTALL.md) covers prerequisites, Windows, uvx, PATH, update and removal.
28
37
  [Latest release](https://github.com/kochetkov-ma/brewdoc/releases/latest) lists actual assets and channel availability.
29
38
 
30
39
  ### Standalone downloads
31
40
 
32
- Use downloads listed as available in the release. Python and dependencies are bundled. Verify [SHA256SUMS](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.0/SHA256SUMS) and keep the entire extracted directory.
41
+ Use downloads listed as available in the release. Python and dependencies are bundled. Verify [SHA256SUMS](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.5.0/SHA256SUMS) and keep the entire extracted directory.
33
42
 
34
- [![Linux x64 download](https://img.shields.io/badge/Linux_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.0/brewdoc-0.4.0-linux-x64.tar.gz)
35
- [![Windows x64 download](https://img.shields.io/badge/Windows_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.0/brewdoc-0.4.0-windows-x64.zip)
36
- [![macOS ARM64 download](https://img.shields.io/badge/macOS_ARM64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.0/brewdoc-0.4.0-macos-arm64.tar.gz)
43
+ [![Linux x64 download](https://img.shields.io/badge/Linux_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.5.0/brewdoc-0.5.0-linux-x64.tar.gz)
44
+ [![Windows x64 download](https://img.shields.io/badge/Windows_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.5.0/brewdoc-0.5.0-windows-x64.zip)
45
+ [![macOS ARM64 download](https://img.shields.io/badge/macOS_ARM64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.5.0/brewdoc-0.5.0-macos-arm64.tar.gz)
37
46
 
38
47
  | Native target | Verification environment | JavaScript |
39
48
  |---|---|---|
@@ -43,15 +52,21 @@ Use downloads listed as available in the release. Python and dependencies are bu
43
52
 
44
53
  Older OSes, Linux musl/ARM64 and macOS Intel are outside this binary set.
45
54
  Windows is unsigned; macOS has an ad hoc signature without Developer ID/notarization.
46
- Linux archives have checksums, without a detached publisher signature. [Download and launch](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/INSTALL.md#standalone).
55
+ Linux archives have checksums, without a detached publisher signature. [Download and launch](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/INSTALL.md#standalone).
47
56
 
48
57
  ### npm
49
58
 
50
59
  [![npm](https://img.shields.io/npm/v/brewdoc)](https://www.npmjs.com/package/brewdoc)
51
60
 
52
61
  npm targets Linux x64/glibc and macOS ARM64. Windows uses the GitHub native download or Python package.
53
- Use npm/npx only when listed as available in [the release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.4.0).
54
- [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/INSTALL.md#npm-and-npx) contains exact-version installation, update and removal instructions.
62
+ Use npm/npx only when listed as available in [the release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.5.0).
63
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/INSTALL.md#npm-and-npx) contains exact-version installation, update and removal instructions.
64
+
65
+ ### Homebrew
66
+
67
+ Use `kochetkov-ma/brew/brewdoc` only when the release lists it as available.
68
+ It installs the complete native bundle on macOS 15+ ARM64 or Linux x64 with system
69
+ glibc 2.35+. See [installation and lifecycle](INSTALL.md#homebrew).
55
70
 
56
71
  ## Usage
57
72
 
@@ -71,12 +86,18 @@ Requests and output collisions are validated before writes. Paths resolve agains
71
86
 
72
87
  ## Markdown and receipts
73
88
 
74
- Successful output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
89
+ Parsed document output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
75
90
  Known omissions, Contents, then anchored units. PDF uses `page/000001`, workbooks `sheet/000001`,
76
- PPTX `slide/000001`, and DOCX/EPUB/HTML `chapter/000001`. Empty declared units remain navigable.
91
+ PPTX/ODP `slide/000001`, and DOCX/EPUB/HTML/ODT/EML `chapter/000001`.
92
+ Empty declared units remain navigable.
77
93
  Metadata holds source/selection/content hashes, conversion tallies and artifact capabilities;
78
94
  it excludes paths, timestamps, permissions and host data. EPUB retains declared publication metadata.
79
95
 
96
+ UTF-8 `.md` and `.txt` use `brewdoc.markdown/passthrough/1`: exact source bytes with
97
+ no generated envelope, contents or anchors. BOM, whitespace, newline variants and absent
98
+ final newline survive; empty input succeeds. The receipt reports route `text`, kind `none`
99
+ and zero units. Without `--out`, the JSON receipt precedes the unchanged body bytes.
100
+
80
101
  Conversion prints one JSON receipt line first. With `--out`, Markdown goes to the file;
81
102
  without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`; URL receipts use `brewdoc.receipt/2`.
82
103
 
@@ -94,7 +115,8 @@ without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`;
94
115
  | `acquisition` | URL provenance, frozen snapshot and capture status |
95
116
 
96
117
  Exit 0 means conversion, 1 refusal and 2 invalid usage. Success does not prove content fidelity or complete JavaScript.
97
- PDF/DOCX/PPTX/workbooks emit ASCII; HTML/EPUB emit UTF-8 without BOM, with LF newlines. JSON keeps ASCII escaping.
118
+ PDF/DOCX/PPTX emit ASCII; workbooks/HTML/EPUB/ODT/ODP/EML emit UTF-8 without BOM, with LF newlines.
119
+ Text pass-through retains the source UTF-8 encoding and newlines. JSON keeps ASCII escaping.
98
120
  The same local file or frozen snapshot produces identical bytes; live pages can change.
99
121
 
100
122
  ## Python API
@@ -125,12 +147,12 @@ brewdoc --url https://example.com/article --render-js --timeout 30 --out article
125
147
  Public destinations, DNS, redirects, TLS, requests and bytes are validated. Ordinary requests use GET;
126
148
  JS admits only the narrow credential-free HN Algolia XHR POST exception. Local HTML never fetches or runs scripts.
127
149
  Optional JS needs installed/bundled prerequisites, refuses unsupported runtimes before HTTP and downloads no engine.
128
- Timing-only expiry can preserve valid partial content; hard failures refuse output. [Full URL/JS limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/FORMATS.md#url-acquisition).
150
+ Timing-only expiry can preserve valid partial content; hard failures refuse output. [Full URL/JS limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#url-acquisition).
129
151
 
130
152
  ## Article mode
131
153
 
132
154
  Introduced in 0.4.0; use a channel listed as available in the release. For Python JS capture, install
133
- `brewdoc[render-js]==0.4.0`; supported standalone bundles include its prerequisites.
155
+ `brewdoc[render-js]==0.5.0`; supported standalone bundles include its prerequisites.
134
156
 
135
157
  ```sh
136
158
  brewdoc page.html --article --out article.md
@@ -152,21 +174,21 @@ without layout or inferred author/date metadata. The source title is unchanged.
152
174
 
153
175
  The receipt's `not_carried` and successful Markdown's Known omissions declare:
154
176
  `body content outside the selected article or main subtree; complete page coverage is not claimed`.
155
- The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/FORMATS.md#article-selection)
177
+ The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#article-selection)
156
178
  defines selection, refusals and limits.
157
179
 
158
- [Source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
180
+ [Earlier source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
159
181
  Ubuntu 22.04 x64/glibc with CPython 3.13.15, and macOS 15 ARM64/Windows Server 2025 x64
160
182
  with CPython 3.14.7. Each passed four independent wheel/sdist base/optional installs;
161
183
  optional JS executed on Unix and refused before requests on Windows. These are selected
162
- tested patches, not a claim about newer versions. CPython 3.12.14 retains the local macOS
163
- full-suite baseline and existing CI smoke checks. Package evidence is separate from the
164
- standalone binaries; other OS/minor combinations, free-threaded CPython and other
184
+ tested patches, not a claim about newer versions. These results predate the 0.5.0 changes.
185
+ CPython 3.12.14 retains the local macOS full-suite baseline and existing CI smoke checks.
186
+ Package evidence is separate from standalone binaries; other OS/minor combinations, free-threaded CPython and other
165
187
  architectures remain untested here.
166
- See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/FORMATS.md#python-package-compatibility).
188
+ See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#python-package-compatibility).
167
189
 
168
- [Format contracts](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/FORMATS.md) | [Corpus](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/benchmarks/CATALOG.md) | [Measurements](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/benchmarks/METHODOLOGY.md) | [Results](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/benchmarks/results/README.md)
169
- [Releasing](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/RELEASING.md) | [Agent entry point](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/llms.txt) | [MIT license](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.0/LICENSE)
190
+ [Format contracts](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md) | [Corpus](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/CATALOG.md) | [Measurements](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/METHODOLOGY.md) | [Results](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/results/README.md)
191
+ [Releasing](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/RELEASING.md) | [Agent entry point](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/llms.txt) | [MIT license](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/LICENSE)
170
192
 
171
193
  ## Related projects
172
194
 
package/package.json CHANGED
@@ -29,8 +29,8 @@
29
29
  "license": "MIT",
30
30
  "name": "brewdoc",
31
31
  "optionalDependencies": {
32
- "brewdoc-darwin-arm64": "0.4.0",
33
- "brewdoc-linux-x64-glibc": "0.4.0"
32
+ "brewdoc-darwin-arm64": "0.5.0",
33
+ "brewdoc-linux-x64-glibc": "0.5.0"
34
34
  },
35
35
  "publishConfig": {
36
36
  "access": "public",
@@ -40,5 +40,5 @@
40
40
  "type": "git",
41
41
  "url": "git+https://github.com/kochetkov-ma/brewdoc.git"
42
42
  },
43
- "version": "0.4.0"
43
+ "version": "0.5.0"
44
44
  }