makespdf 0.1.1__tar.gz

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.
@@ -0,0 +1,134 @@
1
+ # Dependencies
2
+ node_modules
3
+ /.pnp
4
+ .pnp.js
5
+
6
+ # Testing
7
+ coverage/
8
+ *.lcov
9
+ .nyc_output
10
+
11
+ # Production
12
+ build/
13
+ dist/
14
+ .turbo
15
+
16
+ # Misc
17
+ .DS_Store
18
+ *.pem
19
+ .env
20
+ .env.local
21
+ .env.development.local
22
+ .env.test.local
23
+ .env.production.local
24
+ .dev.vars
25
+
26
+ # Process id files (dev-server pid drops, etc.)
27
+ *.pid
28
+
29
+ # Ad-hoc local render/test artifacts
30
+ registration-test.png
31
+ sample-output.pdf
32
+
33
+ # Logs
34
+ *.log
35
+ npm-debug.log*
36
+ yarn-debug.log*
37
+ yarn-error.log*
38
+ lerna-debug.log*
39
+ .pnpm-debug.log*
40
+
41
+ # Editor directories and files
42
+ .idea
43
+ .vscode
44
+ *.suo
45
+ *.ntvs*
46
+ *.njsproj
47
+ *.sln
48
+ *.sw?
49
+ .turbopack-cache
50
+
51
+ # Cloudflare
52
+ .wrangler
53
+ .wranger
54
+ wrangler.toml
55
+
56
+ # `wrangler types` output when run bare from apps/web. Both `cf-typegen`
57
+ # scripts (repo root and apps/web) run the generator from the repo root and
58
+ # write the TRACKED worker-configuration.d.ts there, which is what both
59
+ # tsconfig.json files compile against. This copy is what a bare `wrangler types`
60
+ # in apps/web produces; nothing reads it, so it stays ignored. The path scoping
61
+ # keeps this rule off the root copy, and a .gitignore rule never untracks an
62
+ # already-tracked file anyway.
63
+ apps/web/worker-configuration.d.ts
64
+
65
+ # Next.js
66
+ .next
67
+ out
68
+
69
+ # TanStack
70
+ .tanstack
71
+
72
+ # Test artifacts
73
+ playwright-report/
74
+ test-results/
75
+
76
+ # Generated debug output files (from generate-sample-pdf.ts)
77
+ sample-output.template-resolved.json
78
+ sample-output.layout-commands.json
79
+ sample-output.html
80
+
81
+ # Auto-generated reports and investigation artefacts
82
+ *_REPORT.md
83
+ *_SUMMARY.md
84
+ *_ANALYSIS.md
85
+ *_INVESTIGATION.md
86
+ *_FIX.md
87
+ *COMPLETION*.md
88
+ *PHASE_*.md
89
+
90
+ # TypeScript declaration build artifacts in source directories
91
+ packages/@pdf/*/src/**/*.d.ts
92
+ packages/@pdf/*/src/**/*.d.ts.map
93
+
94
+ # Lock files (using yarn.lock instead)
95
+ bun.lock
96
+
97
+ # Secrets (never commit)
98
+ mailgun-api-do-not-commit.txt
99
+
100
+ # Claude Code local state (per-user, not team-shared)
101
+ .claude/scheduled_tasks.lock
102
+ .claude/worktrees/
103
+
104
+ # Clankerbar task worktrees (one checkout per task, local-only)
105
+ .worktrees/
106
+
107
+ # Markdown-demo e2e artifacts (regenerated on every spec run)
108
+ assets/demos/
109
+
110
+ # Docs-publisher demo-site output (regenerated by build_pdfs.py / CI)
111
+ examples/docs-demo/site/
112
+
113
+ # Scratch work (not committed)
114
+ scratch/
115
+
116
+ # Skill eval per-run outputs — intentional archives go to eval-history/
117
+ eval-results/
118
+ benchmark-results/
119
+
120
+ # Go build artefact for the upgrade container (built by `go build` in
121
+ # containers/upgrade/; the deployed binary is built by the Dockerfile)
122
+ containers/upgrade/upgrade-server
123
+
124
+ # Bakeoff transcripts and logs — agents have read .env into transcripts
125
+ # in the past; keep them local-only. Existing committed copies are still
126
+ # tracked; new runs won't add more.
127
+ bakeoff/**/transcript.json
128
+ bakeoff/**/agent.log
129
+
130
+ # Per-task agent scratch dirs (e.g. .mak160/) - never commit
131
+ .mak[0-9]*/
132
+
133
+ # Per-task scratch dump (e.g. smoke PDFs, crop screenshots) - never commit
134
+ /.tmp/
@@ -0,0 +1,175 @@
1
+ Metadata-Version: 2.5
2
+ Name: makespdf
3
+ Version: 0.1.1
4
+ Summary: Thin Python client for the makesPDF hosted API (Markdown and DSL templates to PDF)
5
+ Project-URL: Homepage, https://makespdf.com
6
+ Project-URL: Documentation, https://makespdf.com/docs/api
7
+ Author: makesPDF
8
+ License: MIT
9
+ Keywords: markdown,pdf,pdf-a,pdf-ua,rendering
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Printing
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Requires-Python: >=3.9
21
+ Provides-Extra: crewai
22
+ Requires-Dist: crewai>=0.80; extra == 'crewai'
23
+ Provides-Extra: dev
24
+ Requires-Dist: build; extra == 'dev'
25
+ Requires-Dist: pytest>=8; extra == 'dev'
26
+ Requires-Dist: twine; extra == 'dev'
27
+ Provides-Extra: langchain
28
+ Requires-Dist: langchain-core>=0.3; extra == 'langchain'
29
+ Provides-Extra: llamaindex
30
+ Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
31
+ Provides-Extra: mkdocs
32
+ Requires-Dist: mkdocs>=1.6; extra == 'mkdocs'
33
+ Provides-Extra: test
34
+ Requires-Dist: pytest>=8; extra == 'test'
35
+ Description-Content-Type: text/markdown
36
+
37
+ # makespdf (Python)
38
+
39
+ Thin Python client for the [makesPDF](https://makespdf.com) hosted API.
40
+ Plain install is a bare HTTP client (stdlib only, zero required
41
+ dependencies): every call is a hosted API call, so billing stays consistent
42
+ with the web app and CLI. Nothing renders offline.
43
+
44
+ ```bash
45
+ pip install makespdf
46
+ # framework shims (all optional):
47
+ pip install makespdf[langchain] # LangChain tool
48
+ pip install makespdf[llamaindex] # LlamaIndex tool
49
+ pip install makespdf[crewai] # CrewAI tool
50
+ pip install makespdf[mkdocs] # MkDocs sibling-PDF hook
51
+ ```
52
+
53
+ ```python
54
+ import os
55
+ from makespdf import MakesPDFClient
56
+
57
+ client = MakesPDFClient(api_key=os.environ["MAKESPDF_API_KEY"])
58
+
59
+ # Markdown -> PDF bytes
60
+ pdf = client.render_md("# Invoice\n\nHello **Ada**.", {"pageSize": "A4"})
61
+ open("invoice.pdf", "wb").write(pdf)
62
+
63
+ # Stored template -> PDF bytes (production / billed)
64
+ pdf = client.render(template_id="invoice-classic", data={"name": "Ada"})
65
+
66
+ # Inline DSL draft (free, watermarked)
67
+ pdf = client.preview('const template = doc(page(col(s("Hi {{name}}"))));',
68
+ {"name": "Ada"})
69
+
70
+ # Cheap pre-flight checks (no rendering)
71
+ print(client.validate_md("## No H1 here"))
72
+ print(client.validate_preview('const template = doc(page(col(s("hi"))));'))
73
+
74
+ # veraPDF compliance check for an existing PDF (auth optional)
75
+ print(client.verify(open("invoice.pdf", "rb").read()))
76
+ ```
77
+
78
+ Module-level convenience functions (`makespdf.render_md(...)`, etc.) use a
79
+ default client built from `MAKESPDF_API_KEY` / `MAKESPDF_BASE_URL`.
80
+
81
+ ## Auth
82
+
83
+ Mint a key at `https://makespdf.com/settings/api-keys`, store it as
84
+ `MAKESPDF_API_KEY`. The client never needs LLM keys — it is REST-only.
85
+
86
+ ## Retry policy
87
+
88
+ `429` and `5xx` are retried up to 3 times with exponential backoff,
89
+ honouring `Retry-After`. Other `4xx` raise immediately (`400` ->
90
+ `ValidationError`, `401` -> `AuthenticationError`, `402` ->
91
+ `PaymentRequiredError`, `404` -> `NotFoundError`).
92
+
93
+ ## Framework shims
94
+
95
+ All lazy — importing `makespdf` never imports a framework. Each shim exposes
96
+ exactly two tools (`makespdf_render_md` over `POST /api/v1/md`,
97
+ `makespdf_render` over `POST /api/v1/render`):
98
+
99
+ ```python
100
+ from makespdf.integrations.langchain import get_langchain_tools
101
+ from makespdf.integrations.llamaindex import get_llamaindex_tools
102
+ from makespdf.integrations.crewai import get_crewai_tools
103
+ from makespdf.integrations.mkdocs_plugin import get_mkdocs_plugin
104
+ from makespdf.integrations.demo import MARKDOWN_DEMO, DSL_DEMO, DATA_DEMO, TEMPLATE_ID_DEMO # shared demo data
105
+ ```
106
+
107
+ Full 5-line examples per runtime (all render the same demo data):
108
+ [LangChain](https://makespdf.com/docs/integrations/langchain?ref=pypi),
109
+ [LlamaIndex](https://makespdf.com/docs/integrations/llamaindex?ref=pypi),
110
+ [CrewAI](https://makespdf.com/docs/integrations/crewai?ref=pypi),
111
+ [LangGraph](https://makespdf.com/docs/integrations/langgraph?ref=pypi) and
112
+ [Vercel AI SDK](https://makespdf.com/docs/integrations/vercel-ai-sdk?ref=pypi).
113
+ LangGraph reuses the LangChain tools; the Vercel AI SDK page is the catalog
114
+ reference for the JS `@makespdf/agent-tools` implementation in the CLI repo.
115
+
116
+ ### MkDocs sibling PDFs
117
+
118
+ After `pip install makespdf[mkdocs]`, the `makespdf` plugin name resolves
119
+ via the registered `mkdocs.plugins` entry point. Each page's source Markdown
120
+ is rendered to a sibling `.pdf` (one billed `/md` render per page).
121
+ Full guide:
122
+ [makespdf.com/docs/integrations/mkdocs](https://makespdf.com/docs/integrations/mkdocs?ref=mkdocs-plugin).
123
+
124
+ ```yaml
125
+ # mkdocs.yml
126
+ plugins:
127
+ - search
128
+ - makespdf
129
+ extra:
130
+ makespdf: { pageSize: A4 } # optional; passed as /md `options`
131
+ # makespdf: { pageSize: A4, combined: true } # also emit site/combined.pdf
132
+ ```
133
+
134
+ Per-page front-matter (same contract as
135
+ [`@makespdf/docusaurus-plugin`](../integrations/docusaurus-plugin/)):
136
+
137
+ ```md
138
+ ---
139
+ pdf: false # skip this page (no PDF, no bill)
140
+ ---
141
+
142
+ ---
143
+
144
+ pdf-template: invoice-classic # render via /render with this templateId
145
+ customer: Ada # remaining keys + markdown/content/title become template data
146
+
147
+ ---
148
+ ```
149
+
150
+ `combined`, `combined_name`, and `pdf_template`/`pdf-template` are control
151
+ keys: they are consumed by the plugin and never sent as `/md` options.
152
+ Template-routed pages are excluded from the combined PDF.
153
+
154
+ Prefer a hooks file instead? MkDocs `hooks:` takes file paths (not
155
+ `module:func` strings), so add a one-line shim, e.g.
156
+ `docs/hooks/makespdf_hook.py`:
157
+
158
+ ```python
159
+ from makespdf.integrations.mkdocs_plugin import on_post_build_hook
160
+ ```
161
+
162
+ and list it under `hooks:` in `mkdocs.yml`.
163
+
164
+ ## Testing
165
+
166
+ ```bash
167
+ pip install -e .[test]
168
+ pytest -m "not integration" # recorded-fixture suite, no network
169
+ ```
170
+
171
+ Live smokes (burns at most one billed render):
172
+
173
+ ```bash
174
+ MAKESPDF_API_KEY=... MAKESPDF_BASE_URL=https://staging.makespdf.com MAKESPDF_SMOKE=1 pytest -m integration
175
+ ```
@@ -0,0 +1,139 @@
1
+ # makespdf (Python)
2
+
3
+ Thin Python client for the [makesPDF](https://makespdf.com) hosted API.
4
+ Plain install is a bare HTTP client (stdlib only, zero required
5
+ dependencies): every call is a hosted API call, so billing stays consistent
6
+ with the web app and CLI. Nothing renders offline.
7
+
8
+ ```bash
9
+ pip install makespdf
10
+ # framework shims (all optional):
11
+ pip install makespdf[langchain] # LangChain tool
12
+ pip install makespdf[llamaindex] # LlamaIndex tool
13
+ pip install makespdf[crewai] # CrewAI tool
14
+ pip install makespdf[mkdocs] # MkDocs sibling-PDF hook
15
+ ```
16
+
17
+ ```python
18
+ import os
19
+ from makespdf import MakesPDFClient
20
+
21
+ client = MakesPDFClient(api_key=os.environ["MAKESPDF_API_KEY"])
22
+
23
+ # Markdown -> PDF bytes
24
+ pdf = client.render_md("# Invoice\n\nHello **Ada**.", {"pageSize": "A4"})
25
+ open("invoice.pdf", "wb").write(pdf)
26
+
27
+ # Stored template -> PDF bytes (production / billed)
28
+ pdf = client.render(template_id="invoice-classic", data={"name": "Ada"})
29
+
30
+ # Inline DSL draft (free, watermarked)
31
+ pdf = client.preview('const template = doc(page(col(s("Hi {{name}}"))));',
32
+ {"name": "Ada"})
33
+
34
+ # Cheap pre-flight checks (no rendering)
35
+ print(client.validate_md("## No H1 here"))
36
+ print(client.validate_preview('const template = doc(page(col(s("hi"))));'))
37
+
38
+ # veraPDF compliance check for an existing PDF (auth optional)
39
+ print(client.verify(open("invoice.pdf", "rb").read()))
40
+ ```
41
+
42
+ Module-level convenience functions (`makespdf.render_md(...)`, etc.) use a
43
+ default client built from `MAKESPDF_API_KEY` / `MAKESPDF_BASE_URL`.
44
+
45
+ ## Auth
46
+
47
+ Mint a key at `https://makespdf.com/settings/api-keys`, store it as
48
+ `MAKESPDF_API_KEY`. The client never needs LLM keys — it is REST-only.
49
+
50
+ ## Retry policy
51
+
52
+ `429` and `5xx` are retried up to 3 times with exponential backoff,
53
+ honouring `Retry-After`. Other `4xx` raise immediately (`400` ->
54
+ `ValidationError`, `401` -> `AuthenticationError`, `402` ->
55
+ `PaymentRequiredError`, `404` -> `NotFoundError`).
56
+
57
+ ## Framework shims
58
+
59
+ All lazy — importing `makespdf` never imports a framework. Each shim exposes
60
+ exactly two tools (`makespdf_render_md` over `POST /api/v1/md`,
61
+ `makespdf_render` over `POST /api/v1/render`):
62
+
63
+ ```python
64
+ from makespdf.integrations.langchain import get_langchain_tools
65
+ from makespdf.integrations.llamaindex import get_llamaindex_tools
66
+ from makespdf.integrations.crewai import get_crewai_tools
67
+ from makespdf.integrations.mkdocs_plugin import get_mkdocs_plugin
68
+ from makespdf.integrations.demo import MARKDOWN_DEMO, DSL_DEMO, DATA_DEMO, TEMPLATE_ID_DEMO # shared demo data
69
+ ```
70
+
71
+ Full 5-line examples per runtime (all render the same demo data):
72
+ [LangChain](https://makespdf.com/docs/integrations/langchain?ref=pypi),
73
+ [LlamaIndex](https://makespdf.com/docs/integrations/llamaindex?ref=pypi),
74
+ [CrewAI](https://makespdf.com/docs/integrations/crewai?ref=pypi),
75
+ [LangGraph](https://makespdf.com/docs/integrations/langgraph?ref=pypi) and
76
+ [Vercel AI SDK](https://makespdf.com/docs/integrations/vercel-ai-sdk?ref=pypi).
77
+ LangGraph reuses the LangChain tools; the Vercel AI SDK page is the catalog
78
+ reference for the JS `@makespdf/agent-tools` implementation in the CLI repo.
79
+
80
+ ### MkDocs sibling PDFs
81
+
82
+ After `pip install makespdf[mkdocs]`, the `makespdf` plugin name resolves
83
+ via the registered `mkdocs.plugins` entry point. Each page's source Markdown
84
+ is rendered to a sibling `.pdf` (one billed `/md` render per page).
85
+ Full guide:
86
+ [makespdf.com/docs/integrations/mkdocs](https://makespdf.com/docs/integrations/mkdocs?ref=mkdocs-plugin).
87
+
88
+ ```yaml
89
+ # mkdocs.yml
90
+ plugins:
91
+ - search
92
+ - makespdf
93
+ extra:
94
+ makespdf: { pageSize: A4 } # optional; passed as /md `options`
95
+ # makespdf: { pageSize: A4, combined: true } # also emit site/combined.pdf
96
+ ```
97
+
98
+ Per-page front-matter (same contract as
99
+ [`@makespdf/docusaurus-plugin`](../integrations/docusaurus-plugin/)):
100
+
101
+ ```md
102
+ ---
103
+ pdf: false # skip this page (no PDF, no bill)
104
+ ---
105
+
106
+ ---
107
+
108
+ pdf-template: invoice-classic # render via /render with this templateId
109
+ customer: Ada # remaining keys + markdown/content/title become template data
110
+
111
+ ---
112
+ ```
113
+
114
+ `combined`, `combined_name`, and `pdf_template`/`pdf-template` are control
115
+ keys: they are consumed by the plugin and never sent as `/md` options.
116
+ Template-routed pages are excluded from the combined PDF.
117
+
118
+ Prefer a hooks file instead? MkDocs `hooks:` takes file paths (not
119
+ `module:func` strings), so add a one-line shim, e.g.
120
+ `docs/hooks/makespdf_hook.py`:
121
+
122
+ ```python
123
+ from makespdf.integrations.mkdocs_plugin import on_post_build_hook
124
+ ```
125
+
126
+ and list it under `hooks:` in `mkdocs.yml`.
127
+
128
+ ## Testing
129
+
130
+ ```bash
131
+ pip install -e .[test]
132
+ pytest -m "not integration" # recorded-fixture suite, no network
133
+ ```
134
+
135
+ Live smokes (burns at most one billed render):
136
+
137
+ ```bash
138
+ MAKESPDF_API_KEY=... MAKESPDF_BASE_URL=https://staging.makespdf.com MAKESPDF_SMOKE=1 pytest -m integration
139
+ ```
@@ -0,0 +1,53 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "makespdf"
7
+ version = "0.1.1"
8
+ description = "Thin Python client for the makesPDF hosted API (Markdown and DSL templates to PDF)"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "makesPDF" }]
13
+ keywords = ["pdf", "markdown", "rendering", "pdf-a", "pdf-ua"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.9",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Topic :: Printing",
24
+ "Topic :: Software Development :: Libraries :: Python Modules",
25
+ ]
26
+ dependencies = []
27
+
28
+ [project.urls]
29
+ Homepage = "https://makespdf.com"
30
+ Documentation = "https://makespdf.com/docs/api"
31
+
32
+ [project.optional-dependencies]
33
+ langchain = ["langchain-core>=0.3"]
34
+ llamaindex = ["llama-index-core>=0.11"]
35
+ crewai = ["crewai>=0.80"]
36
+ mkdocs = ["mkdocs>=1.6"]
37
+ test = ["pytest>=8"]
38
+ dev = ["pytest>=8", "build", "twine"]
39
+
40
+ [project.entry-points."mkdocs.plugins"]
41
+ # Lets `plugins: [makespdf]` resolve after `pip install makespdf[mkdocs]`.
42
+ # Loaded lazily by MkDocs via getattr, so plain `import makespdf` still
43
+ # never imports mkdocs (see makespdf.integrations docstring).
44
+ makespdf = "makespdf.integrations.mkdocs_plugin:MakesPDFPlugin"
45
+
46
+ [tool.hatch.build.targets.wheel]
47
+ packages = ["src/makespdf"]
48
+
49
+ [tool.pytest.ini_options]
50
+ testpaths = ["tests"]
51
+ markers = [
52
+ "integration: live-API smoke tests (skipped unless MAKESPDF_SMOKE=1 and MAKESPDF_API_KEY is set)",
53
+ ]
@@ -0,0 +1,37 @@
1
+ """makesPDF Python client — thin REST wrapper, stdlib only.
2
+
3
+ Plain install has zero required dependencies: every render call is a hosted
4
+ API call (Bearer auth), so billing stays consistent with the web app, CLI,
5
+ and other integrations. Nothing renders offline and no LLM keys are ever
6
+ needed — the client only ever talks to ``/api/v1/*``.
7
+ """
8
+
9
+ from .client import MakesPDFClient, render, render_md, preview, validate_md, validate_preview, verify
10
+ from .errors import (
11
+ MakesPDFError,
12
+ AuthenticationError,
13
+ PaymentRequiredError,
14
+ NotFoundError,
15
+ RateLimitError,
16
+ ValidationError,
17
+ ServerError,
18
+ )
19
+
20
+ __all__ = [
21
+ "MakesPDFClient",
22
+ "render",
23
+ "render_md",
24
+ "preview",
25
+ "validate_md",
26
+ "validate_preview",
27
+ "verify",
28
+ "MakesPDFError",
29
+ "AuthenticationError",
30
+ "PaymentRequiredError",
31
+ "NotFoundError",
32
+ "RateLimitError",
33
+ "ValidationError",
34
+ "ServerError",
35
+ ]
36
+
37
+ __version__ = "0.1.1"