Skip to content

Commit 71f8c0a

Browse files
daniel-crombiedaniel-crombie
committed
Update samples and documentation
- Add DEVELOPMENT.md and INSTALL.md for comprehensive development and installation guides - Update main README.md with improved documentation - Update module READMEs (ilovepdf/, validators/, samples/) - Add new sample scripts for editpdf, pagenumbers, pdftojpg, and validate_pdfa tasks - Update existing sample scripts with enhancements and fixes - Add live samples for advanced use cases - Improve sample documentation and usage examples Update DEVELOPMENT.md
1 parent e2fa6a1 commit 71f8c0a

34 files changed

Lines changed: 674 additions & 159 deletions

‎DEVELOPMENT.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Development Guide
2+
3+
## Setup
4+
5+
1. Clone the repository:
6+
```bash
7+
git clone https://github.com/ilovepdf/ilovepdf-python.git
8+
cd ilovepdf-python
9+
```
10+
11+
2. Create and activate a virtual environment:
12+
```bash
13+
python -m venv venv
14+
source venv/bin/activate # Linux/Mac
15+
# or
16+
venv\Scripts\activate # Windows
17+
```
18+
19+
3. Install dependencies:
20+
```bash
21+
pip install -r requirements_dev.txt
22+
pip install -e .
23+
```
24+
25+
> The `-e .` flag installs the package in editable mode.
26+
27+
## Pyright Configuration
28+
29+
Create `pyrightconfig.json` in the project root:
30+
31+
```json
32+
{
33+
"extraPaths": ["/path/to/lib/python/site-packages"]
34+
}
35+
```
36+
37+
## Environment Variables
38+
39+
Copy `.env.example` to `.env` and configure:
40+
41+
```bash
42+
cp .env.example .env
43+
```
44+
45+
Required variables:
46+
- `ILOVEPDF_PUBLIC_KEY` - Your API public key
47+
- `ILOVEPDF_SECRET_KEY` - Your API secret key
48+
49+
Optional variables:
50+
- `PYTHONLOGLEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
51+
- `FOLDER_SAMPLE_PATH` - Path to sample files for testing
52+
53+
## Running Tests
54+
55+
```bash
56+
# Unit tests only
57+
pytest tests/unit/
58+
59+
# Integration tests (requires API keys)
60+
pytest tests/integration/
61+
62+
# All tests
63+
pytest tests/
64+
```
65+
66+
## Code Style
67+
68+
The project uses:
69+
- **Black** for formatting
70+
- **Ruff** for fast linting and formatting
71+
- **Pyright** for static type checking
72+
73+
Run formatting and linting:
74+
```bash
75+
black .
76+
ruff check .
77+
ruff format .
78+
pyright ilovepdf/
79+
```
80+
81+
For pre-commit hooks (autom
82+
83+
## Adding a New Task
84+
85+
1. Create `ilovepdf/newtask_task.py` extending `Task`
86+
2. Add unit tests in `tests/unit/`
87+
3. Add integration test in `tests/integration/`
88+
4. Add sample script in `samples/`
89+
5. Update `ilovepdf/__init__.py` to export the task
90+
91+
## Project Structure
92+
93+
```
94+
ilovepdf-python/
95+
├── ilovepdf/ # Core library
96+
│ ├── *task.py # Task implementations
97+
│ ├── task.py # Base task class
98+
│ ├── exceptions/ # Custom exceptions
99+
│ └── validators/ # Input validators
100+
├── samples/ # Usage examples
101+
├── tests/ # Unit & integration tests
102+
├── .docker/ # Docker configurations
103+
├── README.md # Main documentation
104+
├── INSTALL.md # Installation guide
105+
└── DEVELOPMENT.md # This file
106+
```
107+
108+
## Docker
109+
110+
Build and run tests in Docker using `docker-compose`:
111+
112+
```bash
113+
# Build images
114+
docker-compose -f .docker/docker-compose.yml build
115+
116+
# Run tests with a specific Python version
117+
docker-compose -f .docker/docker-compose.yml run --rm python310 pytest tests/unit
118+
119+
# Run all tests
120+
docker-compose -f .docker/docker-compose.yml run --rm python310 pytest tests/
121+
```
122+
123+
Available Python versions: `python310`, `python311`, `python312`, `python313`, `python314`
124+
125+
For full Docker instructions, see [`.docker/README.md`](.docker/README.md).
126+
127+
## Getting Help
128+
129+
- Issues: https://github.com/ilovepdf/ilovepdf-python/issues
130+
- API Docs: https://developer.ilovepdf.com/docs

‎INSTALL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Installation Guide
2+
3+
## From PyPI (Recommended)
4+
5+
```bash
6+
pip install ilovepdf
7+
```
8+
9+
## From Source
10+
11+
Install the latest version directly from GitHub:
12+
13+
```bash
14+
pip install -U git+https://github.com/ilovepdf/ilovepdf-python.git@main#egg=ilovepdf
15+
```
16+
17+
## Pre-release Versions
18+
19+
Test upcoming versions from TestPyPI:
20+
21+
```bash
22+
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ilovepdf
23+
```
24+
25+
> **Note:** The `--extra-index-url` flag is required because TestPyPI doesn't host all dependency versions.
26+
27+
## Requirements
28+
29+
- Python 3.10 - 3.14
30+
- Dependencies: `requests>=2.28.0`, `pyjwt>=2.4.0`, `python-dotenv>=1.0.0`
31+
32+
## Virtual Environment (Recommended)
33+
34+
```bash
35+
python -m venv venv
36+
source venv/bin/activate # Linux/Mac
37+
# or
38+
venv\Scripts\activate # Windows
39+
pip install ilovepdf
40+
```

‎README.md‎

Lines changed: 9 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -10,56 +10,30 @@ You can sign up for an iLovePDF account at https://developer.ilovepdf.com
1010

1111
Develop and automate PDF processing tasks like Compress PDF, Merge PDF, Split PDF, convert Office to PDF, PDF to JPG, Images to PDF, add Page Numbers, Rotate PDF, Unlock PDF, stamp a Watermark and Repair PDF. Each one with several settings to get your desired results.
1212

13-
---
14-
1513
## Requirements
1614

1715
- Python 3.10 to 3.14
1816

19-
---
20-
21-
> **Note:**
22-
> This library is fully compatible with Python versions 3.10, 3.11, 3.12, 3.13, and 3.14.
23-
> All features, tests, and Docker environments are validated for this range.
24-
> If you encounter any issues with a supported version, please report them via [GitHub Issues](https://github.com/ilovepdf/ilovepdf-python/issues).
25-
26-
---
27-
2817
## Installation
2918

30-
Install from PyPI:
19+
You can install the library via [PIP](https://pypi.org/project/pip/). Run the following command:
3120

3221
```bash
3322
pip install ilovepdf
3423
```
3524

36-
Or install the latest version from source:
37-
38-
```bash
39-
pip install -U git+https://github.com/ilovepdf/ilovepdf-python.git@main#egg=ilovepdf
40-
```
41-
42-
### Install Pre-release Versions
43-
44-
To test pre-release versions from TestPyPI:
45-
46-
```bash
47-
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ilovepdf
48-
```
49-
50-
**Note:** The `--extra-index-url` flag is required because TestPyPI doesn't host all dependency versions.
51-
52-
---
25+
For other install options (source, pre-release), see [INSTALL.md](INSTALL.md).
5326

54-
## Getting Started
27+
## Quick Start
5528

56-
Simple usage looks like:
29+
1. Get your API keys from [https://developer.ilovepdf.com](https://developer.ilovepdf.com)
30+
2. Run a task:
5731

5832
```python
5933
from ilovepdf import CompressTask
6034

6135
task = CompressTask(public_key="your_public_key", secret_key="your_secret_key")
62-
task.add_file("input.pdf")
36+
task.add_file("document.pdf")
6337
task.execute()
6438
task.download("output_folder")
6539
```
@@ -70,10 +44,9 @@ task.download("output_folder")
7044

7145
- Core library: [`ilovepdf/`](ilovepdf/README.md)
7246
- Example scripts: [`samples/`](samples/README.md)
73-
- **Live/manual test scripts:** [`samples/live/`](samples/live/README.md)
7447
- Unit & integration tests: [`tests/`](tests/README.md)
48+
- Installation: [`INSTALL.md`](INSTALL.md) - All install options
49+
- Development: [`DEVELOPMENT.md`](DEVELOPMENT.md) - Contributing & setup
7550
- Docker & environment setup: [`.docker/`](.docker/README.md)
7651

77-
For detailed API documentation, visit the [official iLovePDF API docs](https://developer.ilovepdf.com/docs).
78-
79-
---
52+
For full API docs, visit [developer.ilovepdf.com](https://developer.ilovepdf.com/docs)

‎ilovepdf/README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,22 @@ This folder contains the core Python source code for interacting with the iLoveP
1919
| `merge_task.py` | Merge multiple PDF files into a single PDF. |
2020
| `office_pdf_task.py` | Convert Office documents (Word, Excel, PowerPoint) to PDF. |
2121
| `pdfocr_task.py` | Perform OCR (Optical Character Recognition) on PDF files. |
22+
| `pdftojpg_task.py` | Convert PDF files to JPG images (pages or extract mode). |
2223
| `pdftopdfa_task.py` | Convert PDF files to PDF/A archival format. |
2324
| `protect_task.py` | Add password protection and permissions to PDF files. |
24-
| `removebackground_task.py` | Remove background from images in PDFs. |
25-
| `resize_task.py` | Resize images within PDFs by width, height, or percentage. |
25+
| `repair_task.py` | Repair corrupted or damaged PDF files. |
2626
| `rotate_task.py` | Rotate PDF pages by specified angles. |
2727
| `sign_task.py` | Digitally sign PDF documents. |
2828
| `split_task.py` | Split PDF files into separate documents. |
2929
| `unlock_task.py` | Remove password protection from PDF files. |
3030
| `watermark_task.py` | Add text or image watermarks to PDFs. |
31+
| `pagenumbers_task.py` | Add page numbers to PDFs with customizable appearance. |
32+
| `editpdf_task.py` | Add and position text, image, SVG, or bottom elements on PDFs. |
33+
| `validate_pdfa_task.py` | Validate PDF/A compliance of PDF files (no conversion). |
3134

3235
#### Other Modules
3336

37+
- `helpers.py`: Helper functions and type definitions (literals, options).
3438
- `file.py`: File handling utilities for tasks.
3539
- `abstract_task_element.py`: AbstractTaskElement base class for task elements.
3640
- `ilovepdf_api.py`: Core API communication logic.
@@ -43,7 +47,7 @@ This folder contains the core Python source code for interacting with the iLoveP
4347

4448
- Keep the code modular and well-documented.
4549
- Ensure all new modules and classes include appropriate docstrings (Google style, in English).
46-
- Any file ending with `*_task.py` must have corresponding unit and integration tests, as well as a sample script (see project root `AGENT.md` for details).
50+
- Any file ending with `*_task.py` must have corresponding unit and integration tests, as well as a sample script
4751
- Use type hints for all public methods and properties.
4852
- Follow PEP 8 and project-specific naming conventions.
4953
- Use the provided validators for input validation in tasks and models.
@@ -54,5 +58,7 @@ This folder contains the core Python source code for interacting with the iLoveP
5458
- [Samples and Usage](../samples/README.md)
5559
- [Testing](../tests/README.md)
5660
- [Docker and Environment Setup](../.docker/README.md)
61+
- [Installation](../INSTALL.md) - All install options
62+
- [Development](../DEVELOPMENT.md) - Contributing & setup
5763

58-
For the official API documentation, visit: [iLovePDF API Docs](https://developer.ilovepdf.com/docs)
64+
For the official API documentation, visit: [iLovePDF API Docs](https://developer.ilovepdf.com/docs)

‎ilovepdf/validators/README.md‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -215,32 +215,19 @@ class ExampleTask:
215215
- No caching or memoization (validation is lightweight)
216216
- Suitable for frequent validation calls
217217

218-
## Future Extensions
219-
220-
Additional validators can be easily added following the same pattern:
221-
222-
```python
223-
# Example: DateValidator (to be added)
224-
class DateValidator:
225-
@staticmethod
226-
def validate_in_range(value, min_date, max_date, param_name):
227-
# Implementation
228-
pass
229-
```
230-
231218
## Testing
232219

233220
Each validator has comprehensive unit tests in `tests/unit/`:
234221
- `test_string_validator.py` - Tests for StringValidator
235222
- `test_int_validator.py` - Tests for IntValidator
236-
- `test_float_validator.py` - Tests for FloatValidator
237-
- `test_date_validator.py` - Tests for DateValidator
223+
- `test_bool_validator.py` - Tests for BoolValidator
238224
- `test_choice_validator.py` - Tests for ChoiceValidator
239225

240226
Run tests with:
241227
```bash
242228
pytest tests/unit/test_string_validator.py -v
243229
pytest tests/unit/test_int_validator.py -v
230+
pytest tests/unit/test_bool_validator.py -v
244231
pytest tests/unit/test_choice_validator.py -v
245232
```
246233

@@ -249,4 +236,3 @@ pytest tests/unit/test_choice_validator.py -v
249236
- `ilovepdf/abstract_task_element.py` - AbstractTaskElement base class
250237
- `ilovepdf/exceptions/` - Exception definitions
251238
- `tests/unit/` - Validator tests
252-
```

0 commit comments

Comments
 (0)