communities API

pynteracta.api.communities.CommunitiesAPI

Bases: ResourceClient

Client for community settings endpoints.

list()

GET /communication/settings/communities.

Returns all communities the caller is allowed to post in.

list_by_view_post_capability(level=None)

GET /communication/settings/communities/view-post.

Restituisce le community in cui l'identità autenticata ha la capability di visualizzazione dei post indicata, nella stessa forma di :meth:list.

Parameters:

Name	Type	Description	Default
level	ViewPostCapabilityLevel | str | None	ViewPostCapabilityLevel (PRIVATE, PUBLIC, ALL) o il suo nome come stringa, senza distinzione di maiuscole. Senza livello la richiesta parte senza parametro e la risposta è quella che decide il server (vedi la documentazione).	None

Raises:

Type	Description
ValueError	Livello non valido; nessuna richiesta parte.

details(community_id)

GET /communication/settings/communities/{communityId}/details.

Parameters:

Name	Type	Description	Default
community_id	int	Unique community identifier.	required

details_bulk(community_ids)

POST /communication/settings/communities/details.

Retrieve details for multiple communities in a single call.

Parameters:

Name	Type	Description	Default
community_ids	list[int]	List of community identifiers.	required

details_bulk_raw(req)

POST community details with a pre-built request DTO (escape hatch).

post_definition(community_id)

GET /communication/settings/communities/{communityId}/post-definition.

Returns the post structure (field definitions, hashtags, workflow) for a community.

Parameters:

Name	Type	Description	Default
community_id	int	Unique community identifier.	required

post_definitions(community_ids)

POST /communication/settings/communities/post-definitions.

Retrieve post definitions for multiple communities in a single call.

Parameters:

Name	Type	Description	Default
community_ids	list[int]	List of community identifiers.	required

post_definitions_raw(req)

POST community post definitions with a pre-built request DTO (escape hatch).

---

Communities by post-view capability

list() returns the communities the caller can post in. list_by_view_post_capability() returns those where the caller can view posts at a given capability level, in the same CommunityList shape.

from pynteracta.client import InteractaClient
from pynteracta.models.facade.communities import ViewPostCapabilityLevel

with InteractaClient(base_url="https://tenant.example.com", credentials=...) as client:
    everything = client.communities.list_by_view_post_capability()
    public = client.communities.list_by_view_post_capability(ViewPostCapabilityLevel.PUBLIC)
    private = client.communities.list_by_view_post_capability("private")  # case-insensitive
    print([c.name for c in public.items_typed])

• level is a ViewPostCapabilityLevel (PRIVATE, PUBLIC, ALL) or its name as a string, in any case. Any other value raises ValueError before the request.
• Without a level the query parameter is not sent and the answer is the server's choice. On the test tenant, with a service account, it matched ALL; every level returned the same 15 communities, while list() returned 9.
• A 403 raises PermissionError; a timeout raises TransportError. One request, never retried.

Facade models

pynteracta.models.facade.communities.CommunityList

Facade over :class:~generated.ListCommunitiesResponseDTO.

Attributes:

Name	Type	Description
raw		The underlying generated DTO.

Source code in src/pynteracta/models/facade/communities.py

class CommunityList:
    """Facade over :class:`~generated.ListCommunitiesResponseDTO`.

    Attributes:
        raw: The underlying generated DTO.
    """

    def __init__(self, raw: generated.ListCommunitiesResponseDTO) -> None:
        self.raw = raw

    @property
    def items(self) -> list[generated.CommunityDTO]:
        """Raw community items (generated stubs)."""
        return self.raw.communities or []

    @property
    def items_typed(self) -> list[Community]:
        """Community items re-validated as typed :class:`Community` facades."""
        result = []
        for item in self.items:
            typed = generated.CommunityDTO1.model_validate(item.root)
            result.append(Community(typed))
        return result

    @classmethod
    def from_dict(cls, data: dict) -> CommunityList:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        return cls(generated.ListCommunitiesResponseDTO.model_validate(data))

items property

Raw community items (generated stubs).

items_typed property

Community items re-validated as typed :class:Community facades.

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_dict(cls, data: dict) -> CommunityList:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    return cls(generated.ListCommunitiesResponseDTO.model_validate(data))

pynteracta.models.facade.communities.Community

Narrow facade over :class:~generated.CommunityDTO1.

Attributes:

Name	Type	Description
raw		The underlying generated DTO; access additional fields via this escape hatch.

Source code in src/pynteracta/models/facade/communities.py

class Community:
    """Narrow facade over :class:`~generated.CommunityDTO1`.

    Attributes:
        raw: The underlying generated DTO; access additional fields via this escape hatch.
    """

    def __init__(self, raw: generated.CommunityDTO1) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        """Unique community identifier."""
        return self.raw.id

    @property
    def name(self) -> str | None:
        """Community name."""
        return self.raw.name

    @property
    def description(self) -> str | None:
        """Community description."""
        return self.raw.description

    @classmethod
    def from_raw(cls, raw: generated.CommunityDTO1) -> Community:
        """Wrap a generated DTO."""
        return cls(raw)

description property

Community description.

id property

Unique community identifier.

name property

Community name.

from_raw(raw) classmethod

Wrap a generated DTO.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_raw(cls, raw: generated.CommunityDTO1) -> Community:
    """Wrap a generated DTO."""
    return cls(raw)

pynteracta.models.facade.communities.CommunityDetail

Facade over :class:~generated.GetCommunityDetailsResponseDTO.

Attributes:

Name	Type	Description
raw		The underlying generated DTO.

Source code in src/pynteracta/models/facade/communities.py

class CommunityDetail:
    """Facade over :class:`~generated.GetCommunityDetailsResponseDTO`.

    Attributes:
        raw: The underlying generated DTO.
    """

    def __init__(self, raw: generated.GetCommunityDetailsResponseDTO) -> None:
        self.raw = raw

    @property
    def community(self) -> Community | None:
        """The community detail, or ``None`` if absent in the response."""
        if self.raw.community is None:
            return None
        typed = generated.CommunityDTO1.model_validate(self.raw.community.root)
        return Community(typed)

    @classmethod
    def from_dict(cls, data: dict) -> CommunityDetail:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        return cls(generated.GetCommunityDetailsResponseDTO.model_validate(data))

community property

The community detail, or None if absent in the response.

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_dict(cls, data: dict) -> CommunityDetail:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    return cls(generated.GetCommunityDetailsResponseDTO.model_validate(data))

pynteracta.models.facade.communities.PostDefinition

Facade over :class:~generated.GetPostDefinitionResponseDTOModel.

Attributes:

Name	Type	Description
raw		The underlying generated DTO.

Source code in src/pynteracta/models/facade/communities.py

class PostDefinition:
    """Facade over :class:`~generated.GetPostDefinitionResponseDTOModel`.

    Attributes:
        raw: The underlying generated DTO.
    """

    def __init__(self, raw: generated.GetPostDefinitionResponseDTOModel) -> None:
        self.raw = raw

    @property
    def community_id(self) -> int | None:
        """Community identifier this definition belongs to."""
        return self.raw.communityId

    @property
    def field_definitions(self) -> list[PostFieldDefinition]:
        """Custom field definitions, re-validated as typed facades."""
        result = []
        for stub in self.raw.fieldDefinitions or []:
            typed = generated.PostFieldDefinitionDTO1.model_validate(stub.root)
            result.append(PostFieldDefinition(typed))
        return result

    @property
    def hashtags(self) -> list[generated.HashtagDTO] | None:
        """Hashtags configured for this community (typed variants)."""
        result = []
        for stub in self.raw.hashtags or []:
            result.append(generated.HashtagDTO.model_validate(stub.root))
        return result or None

    @property
    def custom_fields_enabled(self) -> bool | None:
        """Whether custom fields are enabled."""
        return self.raw.customFieldsEnabled

    @classmethod
    def from_dict(cls, data: dict) -> PostDefinition:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        raw = generated.GetPostDefinitionResponseDTOModel.model_validate(data)
        return cls(raw)

community_id property

Community identifier this definition belongs to.

custom_fields_enabled property

Whether custom fields are enabled.

field_definitions property

Custom field definitions, re-validated as typed facades.

hashtags property

Hashtags configured for this community (typed variants).

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_dict(cls, data: dict) -> PostDefinition:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    raw = generated.GetPostDefinitionResponseDTOModel.model_validate(data)
    return cls(raw)

pynteracta.models.facade.communities.PostFieldDefinition

Facade over :class:~generated.PostFieldDefinitionDTO1.

Attributes:

Name	Type	Description
raw		The underlying generated DTO.

Source code in src/pynteracta/models/facade/communities.py

class PostFieldDefinition:
    """Facade over :class:`~generated.PostFieldDefinitionDTO1`.

    Attributes:
        raw: The underlying generated DTO.
    """

    def __init__(self, raw: generated.PostFieldDefinitionDTO1) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        """Field identifier."""
        return self.raw.id

    @property
    def name(self) -> str | None:
        """Internal field name (e.g. ``column_1459``)."""
        return self.raw.name

    @property
    def label(self) -> str | None:
        """Human-readable field label."""
        return self.raw.label

    @property
    def description(self) -> str | None:
        """Field description / compilation instructions."""
        return self.raw.description

    @property
    def type(self) -> FieldType | None:
        """Typed field type. Returns ``None`` if the raw value is absent or unknown."""
        if self.raw.type is None:
            return None
        try:
            return FieldType(self.raw.type)
        except ValueError:
            return None

    @property
    def type_raw(self) -> int | None:
        """Raw integer field type value, for unknown/future types."""
        return self.raw.type

    @property
    def required(self) -> bool | None:
        """Whether the field is required."""
        return self.raw.required

    @property
    def readonly(self) -> bool | None:
        """Whether the field is read-only."""
        return self.raw.readonly

    @property
    def external_id(self) -> str | None:
        """Stable external identifier set by the API consumer (preferred over label)."""
        return self.raw.externalId

    @property
    def metadata(self) -> dict[str, str] | None:
        """Vendor metadata dict (e.g. ``feedback_max_value``, ``decimal_digits``)."""
        return self.raw.metadata

    @property
    def searchable(self) -> bool | None:
        """Whether the field can be used in ``postFieldFilters``."""
        return self.raw.searchable

    @property
    def sortable(self) -> bool | None:
        """Whether the field can be used in ``orderBy`` (``postCustomField-{id}`` form)."""
        return self.raw.sortable

    @property
    def enum_values(self) -> list[FieldEnumValue]:
        """Allowed enum values for ENUM / ENUM_LIST / HIERARCHICAL_ENUM fields.

        Returns an empty list for non-enum field types.
        Use the ``id`` of each entry as the ``parameters`` value in ``postFieldFilters``.
        """
        result = []
        for raw_val in self.raw.enumValues or []:
            typed = generated.PostFieldConfigEnumValueDTO.model_validate(raw_val.root)
            result.append(FieldEnumValue(typed))
        return result

    @property
    def validations(self) -> list[generated.PostFieldValidationDTO] | None:
        """Validation rules attached to this field."""
        return self.raw.validations

    @classmethod
    def from_raw(cls, raw: generated.PostFieldDefinitionDTO1) -> PostFieldDefinition:
        """Wrap a generated DTO."""
        return cls(raw)

description property

Field description / compilation instructions.

enum_values property

Allowed enum values for ENUM / ENUM_LIST / HIERARCHICAL_ENUM fields.

Returns an empty list for non-enum field types. Use the id of each entry as the parameters value in postFieldFilters.

external_id property

Stable external identifier set by the API consumer (preferred over label).

id property

Field identifier.

label property

Human-readable field label.

metadata property

Vendor metadata dict (e.g. feedback_max_value, decimal_digits).

name property

Internal field name (e.g. column_1459).

readonly property

Whether the field is read-only.

required property

Whether the field is required.

searchable property

Whether the field can be used in postFieldFilters.

sortable property

Whether the field can be used in orderBy (postCustomField-{id} form).

type property

Typed field type. Returns None if the raw value is absent or unknown.

type_raw property

Raw integer field type value, for unknown/future types.

validations property

Validation rules attached to this field.

from_raw(raw) classmethod

Wrap a generated DTO.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_raw(cls, raw: generated.PostFieldDefinitionDTO1) -> PostFieldDefinition:
    """Wrap a generated DTO."""
    return cls(raw)

pynteracta.models.facade.communities.PostDefinitionMap

Facade over :class:~generated.ListPostDefinitionsResponseDTO.

The vendor returns a communityPostDefinitionMap keyed by community ID as a string; this facade exposes it with integer keys.

Attributes:

Name	Type	Description
raw		The underlying generated DTO.

Source code in src/pynteracta/models/facade/communities.py

class PostDefinitionMap:
    """Facade over :class:`~generated.ListPostDefinitionsResponseDTO`.

    The vendor returns a ``communityPostDefinitionMap`` keyed by community ID as a string;
    this facade exposes it with integer keys.

    Attributes:
        raw: The underlying generated DTO.
    """

    def __init__(self, raw: generated.ListPostDefinitionsResponseDTO) -> None:
        self.raw = raw

    @property
    def definitions(self) -> dict[int, PostDefinition]:
        """Post definitions keyed by community ID (integer)."""
        result: dict[int, PostDefinition] = {}
        if self.raw.communityPostDefinitionMap is None:
            return result
        for str_key, stub in self.raw.communityPostDefinitionMap.items():
            typed = generated.GetPostDefinitionResponseDTOModel.model_validate(stub.root)
            result[int(str_key)] = PostDefinition(typed)
        return result

    @classmethod
    def from_dict(cls, data: dict) -> PostDefinitionMap:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        return cls(generated.ListPostDefinitionsResponseDTO.model_validate(data))

definitions property

Post definitions keyed by community ID (integer).

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/communities.py

@classmethod
def from_dict(cls, data: dict) -> PostDefinitionMap:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    return cls(generated.ListPostDefinitionsResponseDTO.model_validate(data))

pynteracta.models.facade.communities.FieldType

Bases: IntEnum

Field type identifiers as defined in the CommunicationSettings vendor documentation.

Source code in src/pynteracta/models/facade/communities.py

class FieldType(IntEnum):
    """Field type identifiers as defined in the CommunicationSettings vendor documentation."""

    INT = 1
    BIGINT = 2
    DECIMAL = 3
    DATE = 4
    DATETIME = 5
    STRING = 6
    ENUM = 7
    ENUM_LIST = 8
    TEXT_AREA = 9
    FLAG = 10
    DELTA_AREA = 11
    FEEDBACK = 12
    HIERARCHICAL_ENUM = 13
    LINK = 14
    GENERIC_ENTITY_LIST = 15

pynteracta.models.facade.communities.ViewPostCapabilityLevel

Bases: StrEnum

Livello della capability di visualizzazione dei post, per communities/view-post.

Accetta anche il nome come stringa, senza distinzione di maiuscole (ViewPostCapabilityLevel("private")); qualunque altro valore solleva ValueError.

Source code in src/pynteracta/models/facade/communities.py

class ViewPostCapabilityLevel(StrEnum):
    """Livello della capability di visualizzazione dei post, per ``communities/view-post``.

    Accetta anche il nome come stringa, senza distinzione di maiuscole
    (``ViewPostCapabilityLevel("private")``); qualunque altro valore solleva ``ValueError``.
    """

    PRIVATE = "PRIVATE"
    PUBLIC = "PUBLIC"
    ALL = "ALL"

    @classmethod
    def _missing_(cls, value: object) -> ViewPostCapabilityLevel | None:
        if isinstance(value, str):
            return cls.__members__.get(value.upper())
        return None