NewTqnia Python SDK

The official Python SDK for the NewTqnia technology news API. It includes synchronous and asynchronous clients, typed immutable models, timeouts, retries, structured errors, and safe HTML/JSON-LD rendering.

Applications displaying API content must preserve returned article URLs and visibly render the supplied Powered by NewTqnia attribution.

Installation

pip install newtqnia

Python 3.10 or newer is supported.

Quick start

from newtqnia import NewTqnia

with NewTqnia() as client:
    digest = client.news.latest(locale="en", limit=5)
    for article in digest.articles:
        print(article.title, article.url)

Arabic and category filtering:

digest = client.news.today(locale="ar", category="ai", limit=5)

The OpenAPI contract currently exposes only today and latest. The SDK deliberately does not invent search, article lookup, category listing, or pagination operations.

Async

import asyncio
from newtqnia import AsyncNewTqnia


async def main():
    async with AsyncNewTqnia() as client:
        digest = await client.news.latest(locale="en", limit=5)
        print(digest.articles)


asyncio.run(main())

Render attributed news

render_html() produces escaped, accessible, RTL-aware markup. It preserves canonical article URLs and includes visible attribution by default:

html = digest.render_html()
json_ld = digest.json_ld()

Pass attribution=False only if the page renders digest.attribution.html() visibly elsewhere. See the rendering guide.

Configuration

client = NewTqnia(
    api_key=os.getenv("NEWTQNIA_API_KEY"),
    application="editorial-dashboard",
    website="https://example.com",
    timeout=15,
    retries=3,
    headers={"X-Trace-Source": "dashboard"},
)

No key is required. Optional keys are sent as X-API-Key. Temporary network failures and HTTP 429, 500, 502, 503, and 504 responses are retried with exponential backoff; Retry-After is honored.

Errors

Catch NewTqniaError broadly or specialized ValidationError, AuthenticationError, AuthorizationError, NotFoundError, ConflictError, RateLimitError, ServerError, TimeoutError, and NetworkError. API errors expose status, request_id, code, retry_after, and body.

Development and release

python -m pytest --cov=newtqnia
ruff check .
mypy src
python -m build
twine check dist/*

PyPI releases use GitHub Actions Trusted Publishing when a v* tag is pushed. Configure the pypi environment for newtqnia/newtqnia-python in PyPI before the first release.

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md.