# Python SDK (/docs/python-sdk)



Overview [#overview]

The `earlyseo-blog` Python package lets you render EarlySEO articles in **Django**, **Flask**, or any Python application. Articles are authored in the EarlySEO dashboard and fetched at runtime by the package.

***

Quick Start with CLI [#quick-start-with-cli]

The fastest way to get started — the CLI detects your framework and scaffolds everything:

```bash
pip install earlyseo-blog
earlyseo-blog
```

The CLI will:

1. Detect your framework (Django or Flask)
2. Ask for your **Site ID** (from Dashboard → Integrations → SDK)
3. Generate starter templates, config, and a `.env` file

***

Framework Guides [#framework-guides]

For step-by-step setup instructions, follow the guide for your framework:

| Framework  | Guide                                | Install                               |
| ---------- | ------------------------------------ | ------------------------------------- |
| **Django** | [Django SDK Guide](/docs/django-sdk) | `pip install "earlyseo-blog[django]"` |
| **Flask**  | [Flask SDK Guide](/docs/flask-sdk)   | `pip install "earlyseo-blog[flask]"`  |

***

Prerequisites [#prerequisites]

* **Python ≥ 3.9**
* An EarlySEO account with at least one published article
* **SDK integration** enabled (Dashboard → Integrations → SDK)
* **Site ID** from the SDK integration card

***

Installation [#installation]

```bash
# Core package (standalone client only)
pip install earlyseo-blog

# With Django support
pip install "earlyseo-blog[django]"

# With Flask support
pip install "earlyseo-blog[flask]"

# With async HTTP/2 support
pip install "earlyseo-blog[async]"
```

***

Standalone Client [#standalone-client]

Use the client directly in any Python code — scripts, APIs, data pipelines, or microservices:

```python
from earlyseo_blog import EarlySeoClient

client = EarlySeoClient(site_id="your-site-id")

# Paginated article list
page = client.get_list_page(1)
for item in page.articles:
    print(item.title, item.slug)

# Full article with HTML content
article = client.get_article("my-slug")
print(article.content_html)
```

Async Client [#async-client]

For high-throughput or async frameworks (FastAPI, Starlette, Quart):

```python
from earlyseo_blog import AsyncEarlySeoClient

async with AsyncEarlySeoClient(site_id="your-site-id") as client:
    page = await client.get_list_page(1)
    article = await client.get_article("my-slug")
```

Install the async extra for HTTP/2 support:

```bash
pip install "earlyseo-blog[async]"
```

***

Configuration Reference [#configuration-reference]

| Setting   | Description                      | Default |
| --------- | -------------------------------- | ------- |
| `site_id` | Your EarlySEO site ID (required) | —       |

**Django**: Set `EARLYSEO_SITE_ID` in `settings.py`.

**Flask**: Set `app.config["EARLYSEO_SITE_ID"]`.

***

Data Models [#data-models]

All API responses are validated with Pydantic v2:

| Model             | Description                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- |
| `Manifest`        | Site manifest — total pages and article count                                         |
| `ArticleListItem` | Article summary for list views (title, slug, meta\_description, featured\_image\_url) |
| `ArticleListPage` | Paginated list of `ArticleListItem` with page metadata                                |
| `Article`         | Full article including `content_html`, SEO fields, and metadata                       |

```python
from earlyseo_blog.models import Article, Manifest, ArticleListPage
```

***

How Publishing Works [#how-publishing-works]

1. Write and publish an article in the EarlySEO dashboard
2. Article data becomes instantly available
3. Your Python app fetches the data at request time
4. Articles include SEO metadata automatically

***

Need Help? [#need-help]

* [Django SDK Guide](/docs/django-sdk)
* [Flask SDK Guide](/docs/flask-sdk)
* [SDK Integration Setup](/docs/sdk)
* [SDK Troubleshooting](/docs/sdk-troubleshooting)
* Email [team@earlyseo.com](mailto:team@earlyseo.com)