pynteracta

pynteracta is an unofficial third-party Python client for the Interacta™ platform by Dinova S.r.l. / Maggioli S.p.A. It is neither sponsored nor endorsed by the vendor.

An unofficial Python 3.12+ library and CLI client for the Interacta™ REST API (external_v2). Synchronous and typed: service-account and Google OAuth2 authentication, ten read resources, a write surface that grows one resource group at a time (tasks, posts, attachment upload and the admin area so far), a Typer CLI with table/JSON/YAML output and file export. Current version and contents: see CHANGELOG.md.

Installation

uv pip install pynteracta
# with YAML output support:
uv pip install "pynteracta[yaml]"
# with Parquet export support:
uv pip install "pynteracta[parquet]"
# with all export formats (yaml + parquet):
uv pip install "pynteracta[export]"

Upgrading from 0.4.x? The API changed completely — see the compatibility note at the end of this page.

Each release is also attached as a wheel and sdist to its GitHub release. To pin an exact tag from the repository instead, pick one from the releases page:

uv pip install "pynteracta @ git+https://github.com/simodalla/pynteracta@vX.Y.Z"

Quickstart — library

from pathlib import Path

from pynteracta.auth import load_service_account_key
from pynteracta.client import InteractaClient

key = load_service_account_key(Path("sa.json"))

with InteractaClient(
    base_url="https://interacta.example.it",
    credentials=key,
) as client:
    # Who am I?
    me = client.users.me()
    ud = me.user_data_typed
    if ud is not None:
        print(ud.firstName, ud.lastName)

    # Lazy pagination over every user
    for user in client.users.iterate(page_size=100):
        print(user.id, user.firstName, user.lastName, user.contactEmail)

    # Filtered, sorted posts of a community
    page = client.posts.list_in_community(
        79, order_by="postCreationTimestamp", order_desc=True, post_types=[1], page_size=50
    )
    for post in page.items_typed:
        print(post.id, post.title, client.web_urls.post(post.id))

Quickstart — CLI

# Authenticate with a service-account key (global options go BEFORE the command)
pynteracta --base-url https://interacta.example.it auth login --service-account-key sa.json

# Who am I?
pynteracta auth whoami

# List users (table output by default); count matching users only
pynteracta users list --all
pynteracta users list --status 1 --count

# Fetch a post as JSON; list a community's posts with filters and validation
pynteracta posts get 21269 --output json
pynteracta posts list --community 79 --mentioned --field-filter 1411:4:226 --validate --web-url

# Export to file (csv / json / yaml / parquet inferred from the extension)
pynteracta posts list --community 79 --all --export posts.parquet

pynteracta --version

Features

• Authentication — service-account RS512 JWT assertion with token lifecycle and file/memory cache (POSIX 0o600/0o700 enforcement), or Google OAuth2 access-token exchange.
• Read resources — auth, users, posts, communities, catalogs, attachments, tasks, groups, hashtags, admin_manage (manage/edit forms). One facade per response with a .raw escape hatch to the generated DTO.
• Write operations — tasks create/edit/delete, custom posts (create, edit, copy, custom data, watchers, attachments, delete, mark-as-erasable, comments, workflow), event posts (create, edit, copy, answer to the invitation), admin users (create, edit, delete, credentials), admin groups (create, edit, delete, members), admin catalogs and catalog entries (create, edit, logical delete, restore) and the admin workspace edit (name, description, members, roles, cover and logo), with explicit kwargs and *_raw variants in the library and tasks … / posts … / users … / groups … / catalogs … / admin-manage edit-workspace write commands in the CLI (confirmation on destructive commands, exit code 9 on occToken conflicts, no automatic retry of uncertain writes).
• Attachment upload — client.attachments.upload() and --attach / attachments upload / posts edit-attachments in the CLI; the uploaded file is attached to posts, comments and tasks, with no Interacta token sent to the storage and signed links redacted from logs.
• Filtering & sorting — curated kwargs/flags for posts and users, custom-field and workflow screen-field filters with opt-in validation against the community post-definition, generic --filter KEY=VALUE passthrough.
• Pagination — lazy iterate*() helpers in Python; --all, --page-token, --count in the CLI.
• CLI output — table / json / yaml, --full and --fields field selection, --web-url deep links, --export to csv/json/yaml/parquet.
• Configuration — 4-level precedence: built-in defaults → config.toml profiles → PYNTERACTA_* env vars → CLI flags; config sub-commands edit the file without losing comments.
• Logging — structured logging with token redaction; optional API call audit log to console and rotating JSON-lines file.

Configuration

Config file: ~/.config/pynteracta/config.toml (Linux/macOS, XDG; %LOCALAPPDATA%\pynteracta\ on Windows).

current_profile = "default"

[profiles.default]
base_url = "https://interacta.example.it"
service_account_key = "~/.config/pynteracta/sa.json"

Environment variables: PYNTERACTA_BASE_URL, PYNTERACTA_SERVICE_ACCOUNT_KEY, PYNTERACTA_LOG_LEVEL, etc. See docs/configuration.md for the full reference.

Documentation

Full documentation: https://simodalla.github.io/pynteracta/

• CLI reference — every command, flag and exit code.
• Guides: filtering and sorting posts, filtering and sorting users.
• Authentication, configuration, audit logging, testing.
• Planning: ROADMAP.md (what ships when), specs/ (one spec per version), WORKFLOW.md (how we work), CHANGELOG.md.

To preview the site locally: uv run mkdocs serve.

License

Apache-2.0 — see LICENSE.

Note for users of pynteracta 0.4.x and earlier

Version 0.9.4 and every later version are a complete rewrite of this project. The package name on PyPI is the same, but the code is not: the library was rebuilt from scratch, and its public API is not compatible with the 0.4.x line. (PyPI jumps straight from 0.4.30 to 0.9.4: the rewrite's earlier versions were released on GitHub only.) Upgrading from 0.4.x will break your code, and there is no migration path — the two versions share no common API surface.

What changed:

If you depend on the old line, it is still published and installable — nothing has been removed or yanked. Pin it explicitly:

uv pip install "pynteracta==0.4.30"

The 0.4.x releases receive no further updates. New work happens on the rewrite.