|
2 | 2 |
|
3 | 3 | ## Why TPPT? |
4 | 4 |
|
5 | | -Even in the current era of widespread generative AI, there are still many requests for submitting reports in pptx format. |
6 | | -(Are we the only ones being left behind?) |
| 5 | +In today's world where generative AI is becoming ubiquitous, many organizations still require reports to be submitted in PowerPoint (pptx) format. |
| 6 | +(Or is it just us who are being left behind?) |
7 | 7 |
|
8 | | -TPPT is a wrapper for python-pptx that provides type-safe usage of slide masters and more. |
| 8 | +TPPT is a powerful wrapper for python-pptx that brings type safety to slide masters and more. |
9 | 9 |
|
10 | | -It also incorporates ideas to make it easy to use and intuitive to write, |
11 | | -hoping to make your pptx generation safer and simpler. |
| 10 | +We've designed it to be both intuitive and easy to use, |
| 11 | +making your PowerPoint generation process safer and more efficient. |
12 | 12 |
|
13 | | -## Reducing Imports |
14 | | -Let's look at the Quick Start again: |
| 13 | +## Minimal Imports |
| 14 | +Let's revisit the Quick Start example: |
15 | 15 | ```python |
16 | 16 | --8<-- "codes/quick_start.py" |
17 | 17 | ``` |
18 | 18 |
|
19 | | -This code only imports TPPT. |
| 19 | +Notice how this code only requires a single import of TPPT. |
20 | 20 |
|
21 | | -You can create PowerPoint presentations with an extremely minimal number of imports. |
| 21 | +With just this minimal import, you can create complete PowerPoint presentations. |
22 | 22 |
|
23 | | -This is an experimental approach to increase the success rate of code generation by AI, |
24 | | -by ensuring that only importing tppt is sufficient. |
| 23 | +This design choice is intentional - by requiring only the TPPT import, |
| 24 | +we aim to improve the success rate of AI-generated code. |
25 | 25 |
|
26 | | -Two techniques are used to achieve this: |
| 26 | +We achieve this through two key techniques: |
27 | 27 |
|
28 | | -### Active Adoption of Literal Types |
29 | | - |
30 | | -For example, the shape of a Shape to be added to a slide can be written in the traditional way: |
| 28 | +### Simplified Unit Specification with Literals |
31 | 29 |
|
| 30 | +Traditionally, specifying shape dimensions in PowerPoint would look like this: |
32 | 31 | ```python |
33 | 32 | --8<-- "codes/quick_start_many_import.py" |
34 | 33 | ``` |
35 | 34 |
|
36 | | -In other words, `tppt.types.Inches(1)` can be written as `(1, "in")`. |
37 | | - |
38 | | -By expressing unit specifications with types using Literals in this way, |
39 | | -we have reduced the imports that were previously necessary. |
| 35 | +With TPPT, you can write the same thing more concisely: `(1, "in")` instead of `tppt.types.Inches(1)`. |
40 | 36 |
|
41 | | -This is about writing; when reading properties, they are always converted to the Inches type, |
42 | | -allowing for addition, subtraction, and comparison. |
| 37 | +This Literal-based approach significantly reduces the number of imports needed. |
43 | 38 |
|
44 | | -### Type Extraction |
| 39 | +While writing values is simplified, reading properties still gives you proper Inches objects, |
| 40 | +allowing you to perform arithmetic operations and comparisons as needed. |
45 | 41 |
|
46 | | -There are places where lambda expressions like `lambda slide: slide...` are used. |
47 | | -This is lazy evaluation, where the type is extracted at the time of element initialization, |
48 | | -and the element is completed by adding operations to it. |
| 42 | +### Smart Type Extraction |
49 | 43 |
|
50 | | -The characteristic of this approach is that instead of importing types and passing them to function arguments, |
51 | | -types are extracted from within the function and used. |
| 44 | +You'll notice places where we use lambda expressions like `lambda slide: slide...`. |
| 45 | +This is a form of lazy evaluation - we extract the type at initialization time |
| 46 | +and then build the element by applying operations to it. |
52 | 47 |
|
53 | | -This further reduces imports for code generation. |
| 48 | +The beauty of this approach is that instead of importing types and passing them as function arguments, |
| 49 | +we extract and use types directly from within the function. |
54 | 50 |
|
55 | | -This method has another advantage. |
56 | | -By extracting operations on the extracted types into functions, |
57 | | -it becomes easier to share components. |
| 51 | +This not only reduces imports but also brings another advantage: |
| 52 | +by extracting type operations into functions, you can easily create reusable components. |
58 | 53 |
|
59 | 54 | ```python |
60 | 55 | --8<-- "codes/apply_sample.py" |
61 | 56 | ``` |
62 | 57 |
|
63 | | -You can create your own modifier functions like `format_text` and easily reuse them. |
| 58 | +You can create and reuse your own formatting functions like `format_text` with ease. |
64 | 59 |
|
65 | | -### Type Safety |
66 | | -This tool is mainly targeted at users who create new slides based on slide masters. |
| 60 | +### Type Safety First |
| 61 | +TPPT is designed primarily for users who create new slides based on slide masters. |
67 | 62 |
|
68 | | -If you're like me, you've probably struggled with giving types to python-pptx's slide masters. |
| 63 | +If you've worked with python-pptx before, you know the struggle of adding type safety to slide masters. |
69 | 64 |
|
70 | | -TPPT allows you to give types to slide masters using declarative type hints like pydantic. |
| 65 | +TPPT solves this by allowing you to define types for slide masters using pydantic-like declarative type hints: |
71 | 66 |
|
72 | 67 | ```python |
73 | 68 | --8<-- "codes/custom_slide_master.py" |
74 | 69 | ``` |
75 | 70 |
|
76 | | -Is writing type definitions yourself tedious? We've prepared a modest tool for you. |
| 71 | +Don't want to write type definitions manually? We've got you covered with a handy tool: |
77 | 72 |
|
78 | 73 | ```bash |
79 | 74 | python -m tppt.tool.ppt2template $YOUR_TEMPLATE.pptx -o $OUTPUT_FILE.py |
80 | 75 | ``` |
81 | 76 |
|
82 | | -After setting placeholders in the slide layout constructor, |
83 | | -you can describe data such as text, pictures, and tables. |
| 77 | +After setting up placeholders in your slide layout constructor, |
| 78 | +you can easily add text, pictures, tables, and other elements. |
84 | 79 |
|
85 | | -All these operations are type-safe! |
| 80 | +And the best part? All these operations are fully type-safe! |
0 commit comments