# ravsinghchandan/pypdf architecture

> Architecture diagram of the GitHub repository ravsinghchandan/pypdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravsinghchandan/pypdf
- Repository: https://github.com/ravsinghchandan/pypdf

## Overview

pypdf is a pure-Python PDF library. The principal workflow is to open a PDF with PdfReader, access document pages and extract text or metadata, then optionally assemble or modify a document with PdfWriter and write a PDF. The map also preserves documented merge, page transformation, annotation, and encryption capabilities. Edges are limited to README statements and relationships visible in the supplied excerpts or SOURCE INDEX; some subsystems are therefore shown without speculative internal wiring.

Main entry points: [`pypdf/_writer.py`](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_writer.py) (PDF writer), [`pypdf/_reader.py`](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_reader.py) (PDF reader), [`pypdf/_page.py`](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_page.py) (Page operations), [`pypdf/_text_extraction/_text_extractor.py`](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_text_extraction/_text_extractor.py) (Text extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_document_io["PDF document I/O"]
  node_reader["PDF reader<br/>[_reader.py]"]
  node_document_common["Document access<br/>[_doc_common.py]"]
  node_writer["PDF writer<br/>[_writer.py]"]
end

subgraph group_page_text["Pages and text"]
  node_page["Page operations<br/>[_page.py]"]
  node_text_extract["Text extraction<br/>[_text_extractor.py]"]
  node_layout_extract["Layout extraction"]
  node_font_decode["Font decoding<br/>[_font.py]"]
  node_glyph_data["Glyph mappings<br/>[adobe_glyphs.py]"]
  node_font_metrics["Font metrics"]
end

subgraph group_pdf_objects["PDF object model"]
  node_pdf_objects["PDF objects<br/>[_base.py]"]
  node_pdf_structures["PDF structures"]
  node_stream_filters["Stream filters<br/>[filters.py]"]
  node_codec_support["Text codecs<br/>[_codecs.py]"]
end

subgraph group_security_metadata["Security and metadata"]
  node_encryption["PDF encryption<br/>[_encryption.py]"]
  node_crypto_providers["Crypto providers"]
  node_xmp_metadata["XMP metadata<br/>[xmp.py]"]
end

subgraph group_extensions["Annotations and actions"]
  node_annotations["Annotations<br/>[_base.py]"]
  node_annotation_types["Annotation types"]
  node_actions["PDF actions<br/>[_actions.py]"]
end

node_user(("Library user"))
node_pdf_input["Input PDF"]
node_pdf_output["Output PDF"]

node_user -->|"opens PDF"| node_reader
node_pdf_input -->|"reads"| node_reader
node_reader -->|"uses document access"| node_document_common
node_reader -->|"uses encryption"| node_encryption
node_reader -->|"provides pages"| node_page
node_reader -->|"reads metadata"| node_xmp_metadata
node_user -->|"requests text"| node_text_extract
node_page -->|"extracts text"| node_text_extract
node_page -->|"uses layout mode"| node_layout_extract
node_text_extract -->|"decodes fonts"| node_font_decode
node_layout_extract -->|"uses extraction helpers"| node_text_extract
node_font_decode -->|"maps glyphs"| node_glyph_data
node_font_decode -->|"uses metrics"| node_font_metrics
node_user -->|"creates or modifies"| node_writer
node_writer -->|"writes PDF"| node_pdf_output
node_writer -->|"uses document access"| node_document_common
node_writer -->|"merges pages"| node_page
node_writer -->|"configures encryption"| node_encryption
node_writer -->|"writes metadata"| node_xmp_metadata
node_reader -->|"resolves objects"| node_pdf_objects
node_document_common -->|"uses structures"| node_pdf_structures
node_pdf_structures -->|"builds on objects"| node_pdf_objects
node_pdf_structures -->|"decodes streams"| node_stream_filters
node_stream_filters -->|"uses codecs"| node_codec_support
node_encryption -->|"selects provider"| node_crypto_providers
node_writer -->|"adds annotations"| node_annotations
node_annotation_types -->|"extends base"| node_annotations
node_page -->|"uses actions"| node_actions

click node_reader "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_reader.py"
click node_document_common "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_doc_common.py"
click node_writer "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_writer.py"
click node_page "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_page.py"
click node_text_extract "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_text_extraction/_text_extractor.py"
click node_layout_extract "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_text_extraction/_layout_mode/_fixed_width_page.py"
click node_font_decode "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_font.py"
click node_glyph_data "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/adobe_glyphs.py"
click node_font_metrics "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/core_font_metrics.py"
click node_pdf_objects "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/generic/_base.py"
click node_pdf_structures "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/generic/_data_structures.py"
click node_stream_filters "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/filters.py"
click node_codec_support "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/_codecs.py"
click node_encryption "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_encryption.py"
click node_crypto_providers "https://github.com/ravsinghchandan/pypdf/tree/main/pypdf/_crypt_providers"
click node_xmp_metadata "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/xmp.py"
click node_annotations "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/annotations/_base.py"
click node_annotation_types "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/annotations/_markup_annotations.py"
click node_actions "https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/actions/_actions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_reader,node_document_common,node_writer,node_user toneBlue
class node_page,node_text_extract,node_layout_extract,node_font_decode,node_glyph_data,node_font_metrics toneAmber
class node_pdf_objects,node_pdf_structures,node_stream_filters,node_codec_support toneMint
class node_encryption,node_crypto_providers,node_xmp_metadata toneRose
class node_annotations,node_annotation_types,node_actions,node_pdf_input,node_pdf_output toneIndigo
```

## Components

### PDF document I/O

- [PDF reader](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_reader.py): `pypdf/_reader.py`
- [Document access](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_doc_common.py): `pypdf/_doc_common.py`
- [PDF writer](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_writer.py): `pypdf/_writer.py`

### Pages and text

- [Page operations](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_page.py): `pypdf/_page.py`
- [Text extraction](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_text_extraction/_text_extractor.py): `pypdf/_text_extraction/_text_extractor.py`
- [Layout extraction](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_text_extraction/_layout_mode/_fixed_width_page.py): `pypdf/_text_extraction/_layout_mode/_fixed_width_page.py`
- [Font decoding](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_font.py): `pypdf/_font.py`
- [Glyph mappings](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/adobe_glyphs.py): `pypdf/_codecs/adobe_glyphs.py`
- [Font metrics](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/core_font_metrics.py): `pypdf/_codecs/core_font_metrics.py`

### PDF object model

- [PDF objects](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/generic/_base.py): `pypdf/generic/_base.py`
- [PDF structures](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/generic/_data_structures.py): `pypdf/generic/_data_structures.py`
- [Stream filters](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/filters.py): `pypdf/filters.py`
- [Text codecs](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_codecs/_codecs.py): `pypdf/_codecs/_codecs.py`

### Security and metadata

- [PDF encryption](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/_encryption.py): `pypdf/_encryption.py`
- [Crypto providers](https://github.com/ravsinghchandan/pypdf/tree/main/pypdf/_crypt_providers): `pypdf/_crypt_providers`
- [XMP metadata](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/xmp.py): `pypdf/xmp.py`

### Annotations and actions

- [Annotations](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/annotations/_base.py): `pypdf/annotations/_base.py`
- [Annotation types](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/annotations/_markup_annotations.py): `pypdf/annotations/_markup_annotations.py`
- [PDF actions](https://github.com/ravsinghchandan/pypdf/blob/main/pypdf/actions/_actions.py): `pypdf/actions/_actions.py`

### Other components

- **Library user**
- **Input PDF**
- **Output PDF**

## Connections

- Library user → PDF reader: opens PDF
- Input PDF → PDF reader: reads
- PDF reader → Document access: uses document access (evidence: `pypdf/_reader.py`)
- PDF reader → PDF encryption: uses encryption (evidence: `pypdf/_reader.py`)
- PDF reader → Page operations: provides pages (evidence: `pypdf/_reader.py`)
- PDF reader → XMP metadata: reads metadata (evidence: `pypdf/_reader.py`)
- Library user → Text extraction: requests text
- Page operations → Text extraction: extracts text (evidence: `pypdf/_page.py`)
- Page operations → Layout extraction: uses layout mode (evidence: `pypdf/_page.py`)
- Text extraction → Font decoding: decodes fonts (evidence: `pypdf/_text_extraction/_text_extractor.py`)
- Layout extraction → Text extraction: uses extraction helpers (evidence: `pypdf/_text_extraction/_layout_mode/_fixed_width_page.py`)
- Font decoding → Glyph mappings: maps glyphs (evidence: `pypdf/_font.py`)
- Font decoding → Font metrics: uses metrics (evidence: `pypdf/_font.py`)
- Library user → PDF writer: creates or modifies
- PDF writer → Output PDF: writes PDF
- PDF writer → Document access: uses document access (evidence: `pypdf/_writer.py`)
- PDF writer → Page operations: merges pages (evidence: `pypdf/_writer.py`)
- PDF writer → PDF encryption: configures encryption (evidence: `pypdf/_writer.py`)
- PDF writer → XMP metadata: writes metadata (evidence: `pypdf/_writer.py`)
- PDF reader → PDF objects: resolves objects (evidence: `pypdf/_reader.py`)
- Document access → PDF structures: uses structures (evidence: `pypdf/_doc_common.py`)
- PDF structures → PDF objects: builds on objects (evidence: `pypdf/generic/_data_structures.py`)
- PDF structures → Stream filters: decodes streams (evidence: `pypdf/generic/_data_structures.py`)
- Stream filters → Text codecs: uses codecs (evidence: `pypdf/filters.py`)
- PDF encryption → Crypto providers: selects provider (evidence: `pypdf/_encryption.py`)
- PDF writer → Annotations: adds annotations (evidence: `pypdf/_writer.py`)
- Annotation types → Annotations: extends base (evidence: `pypdf/annotations/_markup_annotations.py`)
- Page operations → PDF actions: uses actions (evidence: `pypdf/_page.py`)
