article 0.0.1__tar.gz → 0.1.2__tar.gz

article-0.1.2/.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,toml,yml,yaml}]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

article-0.1.2/.env.example

@@ -0,0 +1,35 @@
+# article — configuration & secrets (copy to `.env`; never commit the real .env)
+# Loaded by article.config.Settings via pydantic-settings.
+# Every platform is optional: omit a platform's secrets to skip it.
+
+# --- Substack (Phase 1, primary) ---------------------------------------------
+# Public URL of your publication; the canonical SSOT URL is derived from it.
+SUBSTACK_PUBLICATION_URL=https://yourname.substack.com
+# Credentials are only needed when no saved browser session exists yet.
+SUBSTACK_EMAIL=you@example.com
+SUBSTACK_PASSWORD=
+# Where the Playwright storage_state (cookies/session) is persisted/reused.
+SUBSTACK_SESSION_PATH=.article/substack_session.json
+
+# --- Medium (Phase 2) --------------------------------------------------------
+# Self-issued integration token: Settings > Security and apps > Integration tokens.
+# NOTE: Medium's API is deprecated but still works with a self-issued token.
+MEDIUM_TOKEN=
+MEDIUM_USER_ID=
+
+# --- Dev.to / Forem (Phase 2) ------------------------------------------------
+# Generate at https://dev.to/settings/extensions ("DEV API Keys").
+DEVTO_API_KEY=
+
+# --- Hashnode (Phase 2) ------------------------------------------------------
+# Personal Access Token from https://hashnode.com/settings/developer
+HASHNODE_TOKEN=
+# Publication ObjectId (query `publication(host: "...") { id }`).
+HASHNODE_PUBLICATION_ID=
+
+# --- Pipeline ----------------------------------------------------------------
+# JSON state store; the canonical_url SSOT lives here, keyed by article slug.
+STATE_PATH=pipeline_state.json
+# Human-like pacing window (seconds) for browser automation.
+MIN_ACTION_DELAY=0.6
+MAX_ACTION_DELAY=2.4

article-0.1.2/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: article
+Version: 0.1.2
+Summary: Tools to semi-automate the publication of articles
+Project-URL: Homepage, https://github.com/thorwhalen/article
+Project-URL: Repository, https://github.com/thorwhalen/article
+Project-URL: Documentation, https://thorwhalen.github.io/article
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,canonical-url,dev.to,hashnode,medium,publishing,seo,substack,syndication
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: argh
+Requires-Dist: httpx
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv
+Provides-Extra: completion
+Requires-Dist: argcomplete; extra == 'completion'
+Provides-Extra: dev
+Requires-Dist: playwright; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: substack
+Requires-Dist: playwright; extra == 'substack'
+Description-Content-Type: text/markdown
+
+# article
+
+Tools to semi-automate the publication of articles.
+
+Write an article **once** as a JSON file. Publish it to a **primary** platform
+(Substack), then **syndicate** it to secondary platforms (Medium, Dev.to,
+Hashnode) — each pointing its canonical URL back to the primary, so you get
+cross-platform reach without an SEO duplicate-content penalty.
+
+```bash
+pip install article
+```
+
+## The single source of truth
+
+The Substack public URL captured in phase 1 is the SSOT. It is stored
+(keyed by article slug) and injected as `canonical_url` into every secondary
+platform in phase 2, so each emits `<link rel="canonical" href="…">` pointing
+back at the original.
+
+```
+author.json ──► publish-primary ──► Substack ──► live URL ─┐
+                                                           │ stored as canonical_url
+                                                           ▼  (pipeline_state.json, by slug)
+                          syndicate-secondary ──► Medium / Dev.to / Hashnode
+                                                  each canonical → Substack URL
+```
+
+The two phases are deliberately separate commands so you can syndicate later
+(e.g. `+3 days`) on your own schedule.
+
+## Two-command flow
+
+```bash
+# 1. Author once, then publish to the primary (records the canonical URL):
+python -m article publish-primary article.json
+
+# 2. Later — syndicate everywhere, injecting the canonical URL for SEO:
+python -m article syndicate-secondary article.json
+
+# Subset / machine-readable output:
+python -m article syndicate-secondary article.json --platforms medium,dev_to --json-out
+```
+
+After `pip install`, the `article` console script is equivalent
+(`article publish-primary article.json`).
+
+## The article JSON
+
+One standardized file is the single source of truth for content **and** which
+platforms to publish to — a platform is published only if it appears under
+`platforms` (see [`examples/article.example.json`](examples/article.example.json)):
+
+```json
+{
+  "title": "Designing an SSOT Publishing Pipeline",
+  "slug": "ssot-publishing-pipeline",
+  "content_markdown": "# Designing an SSOT Publishing Pipeline\n\n…",
+  "tags": ["python", "automation", "seo"],
+  "platforms": {
+    "substack": { "publish_as_draft": false },
+    "medium":   { "publish_as_draft": true },
+    "dev_to":   { "publish_as_draft": true },
+    "hashnode": { "publish_as_draft": true }
+  }
+}
+```
+
+## Configuration
+
+Secrets and settings load from `.env` (see
+[`.env.example`](.env.example)) — copy it and fill in what you use:
+
+```bash
+cp .env.example .env
+```
+
+Every platform is optional; omit a platform's secrets (or its `platforms`
+entry) to skip it.
+
+## Using it from Python
+
+The CLI is a thin wrapper over the same functions, so everything is callable
+programmatically:
+
+```python
+import asyncio
+from article import load_article, publish_primary, syndicate_secondary
+
+art = load_article("article.json")
+asyncio.run(publish_primary(art))  # phase 1 → records canonical_url
+asyncio.run(syndicate_secondary(art))  # phase 2 → canonical SEO everywhere
+```
+
+## Adding a platform
+
+Adapters are registered in an open-closed registry. To add a platform, write
+one async function satisfying the `PublishAdapter` protocol and register it —
+no core changes:
+
+```python
+from article import register_adapter, PublishResult
+from article.util import require_canonical_url
+
+
+@register_adapter("my_platform")
+async def publish(article, *, canonical_url, config, secrets):
+    require_canonical_url("my_platform", canonical_url)  # SSOT is never optional
+    # … call the platform's API, injecting canonical_url …
+    return PublishResult.success("my_platform", url="…", canonical_url=canonical_url)
+```
+
+## Architecture
+
+| Layer | Module | Responsibility |
+|------|--------|----------------|
+| Schema + config | `article/config.py` | Pydantic `Article` model, `.env` `Settings`, `load_article` (friendly errors) |
+| Vocabulary | `article/base.py` | `PublishResult`, `RunSummary`, platform names, exceptions |
+| State store | `article/state.py` | `MutableMapping` facade over JSON, keyed by slug (the SSOT) |
+| Registry | `article/registry.py` | `PublishAdapter` protocol + open-closed registry |
+| Engine | `article/engine.py` | Orchestrates phase 1 → phase 2; canonical handoff; graceful errors |
+| Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
+| CLI | `article/__main__.py` | `argh` dispatch of the two commands |
+
+> **Status:** the layers above are complete and tested; each adapter's actual
+> network / Playwright call is a clearly-marked `TODO` stub that returns a typed
+> placeholder result. Payload field names are verified against each platform's
+> live API (`canonicalUrl` / `canonical_url` / `originalArticleURL`).

article-0.1.2/README.md

@@ -0,0 +1,128 @@
+# article
+
+Tools to semi-automate the publication of articles.
+
+Write an article **once** as a JSON file. Publish it to a **primary** platform
+(Substack), then **syndicate** it to secondary platforms (Medium, Dev.to,
+Hashnode) — each pointing its canonical URL back to the primary, so you get
+cross-platform reach without an SEO duplicate-content penalty.
+
+```bash
+pip install article
+```
+
+## The single source of truth
+
+The Substack public URL captured in phase 1 is the SSOT. It is stored
+(keyed by article slug) and injected as `canonical_url` into every secondary
+platform in phase 2, so each emits `<link rel="canonical" href="…">` pointing
+back at the original.
+
+```
+author.json ──► publish-primary ──► Substack ──► live URL ─┐
+                                                           │ stored as canonical_url
+                                                           ▼  (pipeline_state.json, by slug)
+                          syndicate-secondary ──► Medium / Dev.to / Hashnode
+                                                  each canonical → Substack URL
+```
+
+The two phases are deliberately separate commands so you can syndicate later
+(e.g. `+3 days`) on your own schedule.
+
+## Two-command flow
+
+```bash
+# 1. Author once, then publish to the primary (records the canonical URL):
+python -m article publish-primary article.json
+
+# 2. Later — syndicate everywhere, injecting the canonical URL for SEO:
+python -m article syndicate-secondary article.json
+
+# Subset / machine-readable output:
+python -m article syndicate-secondary article.json --platforms medium,dev_to --json-out
+```
+
+After `pip install`, the `article` console script is equivalent
+(`article publish-primary article.json`).
+
+## The article JSON
+
+One standardized file is the single source of truth for content **and** which
+platforms to publish to — a platform is published only if it appears under
+`platforms` (see [`examples/article.example.json`](examples/article.example.json)):
+
+```json
+{
+  "title": "Designing an SSOT Publishing Pipeline",
+  "slug": "ssot-publishing-pipeline",
+  "content_markdown": "# Designing an SSOT Publishing Pipeline\n\n…",
+  "tags": ["python", "automation", "seo"],
+  "platforms": {
+    "substack": { "publish_as_draft": false },
+    "medium":   { "publish_as_draft": true },
+    "dev_to":   { "publish_as_draft": true },
+    "hashnode": { "publish_as_draft": true }
+  }
+}
+```
+
+## Configuration
+
+Secrets and settings load from `.env` (see
+[`.env.example`](.env.example)) — copy it and fill in what you use:
+
+```bash
+cp .env.example .env
+```
+
+Every platform is optional; omit a platform's secrets (or its `platforms`
+entry) to skip it.
+
+## Using it from Python
+
+The CLI is a thin wrapper over the same functions, so everything is callable
+programmatically:
+
+```python
+import asyncio
+from article import load_article, publish_primary, syndicate_secondary
+
+art = load_article("article.json")
+asyncio.run(publish_primary(art))  # phase 1 → records canonical_url
+asyncio.run(syndicate_secondary(art))  # phase 2 → canonical SEO everywhere
+```
+
+## Adding a platform
+
+Adapters are registered in an open-closed registry. To add a platform, write
+one async function satisfying the `PublishAdapter` protocol and register it —
+no core changes:
+
+```python
+from article import register_adapter, PublishResult
+from article.util import require_canonical_url
+
+
+@register_adapter("my_platform")
+async def publish(article, *, canonical_url, config, secrets):
+    require_canonical_url("my_platform", canonical_url)  # SSOT is never optional
+    # … call the platform's API, injecting canonical_url …
+    return PublishResult.success("my_platform", url="…", canonical_url=canonical_url)
+```
+
+## Architecture
+
+| Layer | Module | Responsibility |
+|------|--------|----------------|
+| Schema + config | `article/config.py` | Pydantic `Article` model, `.env` `Settings`, `load_article` (friendly errors) |
+| Vocabulary | `article/base.py` | `PublishResult`, `RunSummary`, platform names, exceptions |
+| State store | `article/state.py` | `MutableMapping` facade over JSON, keyed by slug (the SSOT) |
+| Registry | `article/registry.py` | `PublishAdapter` protocol + open-closed registry |
+| Engine | `article/engine.py` | Orchestrates phase 1 → phase 2; canonical handoff; graceful errors |
+| Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
+| CLI | `article/__main__.py` | `argh` dispatch of the two commands |
+
+> **Status:** the layers above are complete and tested; each adapter's actual
+> network / Playwright call is a clearly-marked `TODO` stub that returns a typed
+> placeholder result. Payload field names are verified against each platform's
+> live API (`canonicalUrl` / `canonical_url` / `originalArticleURL`).

article-0.1.2/article/__init__.py

@@ -0,0 +1,141 @@
+"""article — semi-automate single-source-of-truth article publishing.
+
+Author an article once as a JSON file, publish it to a **primary** platform
+(Substack), then **syndicate** it to secondaries (Medium, Dev.to, Hashnode)
+with correct canonical-URL SEO. The Substack public URL captured in phase 1 is
+the single source of truth (SSOT) injected as ``canonical_url`` into every
+secondary in phase 2.
+
+Quick start (Python)::
+
+    import asyncio
+    from article import load_article, publish_primary, syndicate_secondary
+
+    art = load_article("article.json")
+    asyncio.run(publish_primary(art))        # phase 1 -> records canonical_url
+    asyncio.run(syndicate_secondary(art))    # phase 2 -> canonical SEO everywhere
+
+Or via the CLI::
+
+    python -m article publish-primary     article.json
+    python -m article syndicate-secondary article.json
+
+The public surface below is curated; everything else is an implementation
+detail. Importing this package registers the built-in platform adapters.
+
+>>> from article import load_article, available_adapters
+>>> load_article({"title": "T", "slug": "t", "content_markdown": "x"}).slug
+'t'
+>>> available_adapters()
+('dev_to', 'hashnode', 'medium', 'substack')
+"""
+
+from __future__ import annotations
+
+# Vocabulary / result types / exceptions
+from .base import (
+    ALL_PLATFORMS,
+    DEV_TO,
+    HASHNODE,
+    MEDIUM,
+    PRIMARY_PLATFORM,
+    SECONDARY_PLATFORMS,
+    SUBSTACK,
+    AdapterError,
+    ArticleError,
+    ArticleValidationError,
+    CanonicalUrlMissing,
+    ConfigError,
+    Phase,
+    PlatformName,
+    PublishResult,
+    PublishState,
+    RunSummary,
+    UnknownPlatformError,
+)
+
+# Domain schema + config facade
+from .config import (
+    Article,
+    DevToConfig,
+    HashnodeConfig,
+    MediumConfig,
+    PlatformConfigs,
+    Settings,
+    SubstackConfig,
+    load_article,
+    load_settings,
+)
+
+# State store (MutableMapping facade)
+from .state import JsonStateStore, default_state_store
+
+# Adapter Protocol + open-closed registry
+from .registry import (
+    PublishAdapter,
+    available_adapters,
+    get_adapter,
+    is_registered,
+    register_adapter,
+)
+
+# Orchestration engine + module-level facade
+from .engine import (
+    PipelineEngine,
+    build_engine,
+    publish_primary,
+    syndicate_secondary,
+)
+
+# Importing the adapters package registers all built-in adapters.
+from . import adapters  # noqa: F401  (side-effect: populate the registry)
+
+__all__ = [
+    # domain
+    "Article",
+    "PlatformConfigs",
+    "SubstackConfig",
+    "MediumConfig",
+    "DevToConfig",
+    "HashnodeConfig",
+    "load_article",
+    # config / settings
+    "Settings",
+    "load_settings",
+    # results / vocabulary
+    "PublishResult",
+    "PublishState",
+    "RunSummary",
+    "Phase",
+    "PlatformName",
+    "PRIMARY_PLATFORM",
+    "SECONDARY_PLATFORMS",
+    "ALL_PLATFORMS",
+    "SUBSTACK",
+    "MEDIUM",
+    "DEV_TO",
+    "HASHNODE",
+    # errors
+    "ArticleError",
+    "ArticleValidationError",
+    "ConfigError",
+    "AdapterError",
+    "UnknownPlatformError",
+    "CanonicalUrlMissing",
+    # state
+    "JsonStateStore",
+    "default_state_store",
+    # registry
+    "PublishAdapter",
+    "register_adapter",
+    "get_adapter",
+    "available_adapters",
+    "is_registered",
+    # engine
+    "PipelineEngine",
+    "build_engine",
+    "publish_primary",
+    "syndicate_secondary",
+]
+
+__version__ = "0.1.0"

article-0.1.2/article/__main__.py

@@ -0,0 +1,106 @@
+# PYTHON_ARGCOMPLETE_OK
+"""Command-line entry point for the ``article`` publishing pipeline.
+
+Two commands, mirroring the two phases — both thin wrappers over the very same
+:mod:`article.engine` functions the Python API exposes (dispatch-to-interface:
+one implementation, many front-ends)::
+
+    python -m article publish-primary      article.json
+    python -m article syndicate-secondary  article.json
+
+Common options: ``--env-file`` (where to read secrets), ``--state-path``
+(the SSOT state file), ``--json-out`` (machine-readable summary). Phase 2 also
+takes ``--platforms medium,dev_to`` to syndicate a subset.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import argh
+
+from .base import ArticleError, RunSummary
+from .config import load_article, load_settings
+from .engine import publish_primary as _publish_primary
+from .engine import syndicate_secondary as _syndicate_secondary
+from .state import JsonStateStore
+from .util import run_sync
+
+
+def _render(summary: RunSummary, *, json_out: bool) -> str:
+    return json.dumps(summary.as_record(), indent=2) if json_out else summary.render()
+
+
+def _prepare(article_path: str, *, env_file: Optional[str], state_path: Optional[str]):
+    """Shared setup: load settings + article + state store (with friendly errors)."""
+    try:
+        overrides = {"state_path": state_path} if state_path else {}
+        settings = load_settings(env_file=env_file, **overrides)
+        article = load_article(article_path)
+    except ArticleError as e:
+        raise argh.CommandError(str(e)) from e
+    store = JsonStateStore(settings.state_path)
+    return settings, article, store
+
+
+@argh.arg("article_path", help="Path to the article JSON file")
+def publish_primary(
+    article_path: str,
+    *,
+    env_file: Optional[str] = None,
+    state_path: Optional[str] = None,
+    json_out: bool = False,
+):
+    """Phase 1 — publish to the primary platform (Substack) and record canonical_url."""
+    settings, article, store = _prepare(
+        article_path, env_file=env_file, state_path=state_path
+    )
+    summary = run_sync(_publish_primary(article, settings=settings, store=store))
+    return _render(summary, json_out=json_out)
+
+
+@argh.arg("article_path", help="Path to the article JSON file")
+def syndicate_secondary(
+    article_path: str,
+    *,
+    env_file: Optional[str] = None,
+    state_path: Optional[str] = None,
+    platforms: Optional[str] = None,
+    json_out: bool = False,
+):
+    """Phase 2 — syndicate to secondary platforms, injecting canonical_url for SEO."""
+    settings, article, store = _prepare(
+        article_path, env_file=env_file, state_path=state_path
+    )
+    selected = [p.strip() for p in platforms.split(",")] if platforms else None
+    try:
+        summary = run_sync(
+            _syndicate_secondary(
+                article, settings=settings, store=store, platforms=selected
+            )
+        )
+    except ArticleError as e:
+        raise argh.CommandError(str(e)) from e
+    return _render(summary, json_out=json_out)
+
+
+#: SSOT list of dispatchable commands (argh maps ``_`` in names to ``-``).
+_dispatch_funcs = [publish_primary, syndicate_secondary]
+
+
+def main() -> None:
+    """Assemble the argh parser and dispatch (with optional tab completion)."""
+    parser = argh.ArghParser()
+    parser.add_commands(_dispatch_funcs)
+    try:
+        import argcomplete
+
+        argcomplete.autocomplete(parser)
+    except ImportError:
+        pass
+    parser.dispatch()
+
+
+if __name__ == "__main__":
+    main()

article-0.1.2/article/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Built-in platform adapters.
+
+Importing this package has the side effect of registering every built-in
+adapter in :mod:`article.registry`. The top-level :mod:`article` package
+imports it, so the registry is populated as soon as ``article`` is imported.
+
+To add a platform: drop a new module here that decorates an async function with
+``@register_adapter("<name>")``, then import it below. No core code changes.
+"""
+
+from __future__ import annotations
+
+# Side-effect imports: each module registers its adapter on import.
+from . import substack  # noqa: F401
+from . import medium  # noqa: F401
+from . import dev_to  # noqa: F401
+from . import hashnode  # noqa: F401