Skip to content
Last updated

Python SDK for Pigello API

A Python SDK for querying, writing, deleting, and constructing data against the Pigello API. It is fully typed and can be a practical alternative to reading the raw documentation.

Introduction

The SDK helps you with:

  • Querying — Fetch entities and lists with filters and ordering.
  • Writing — Create and update data via the API.
  • Deleting — Remove entities where the API allows.
  • Constructing data — Build request payloads with typed entities.

Because it is completely typed, your editor and type checker can help you use the API correctly without constantly checking the docs.

Requirements

  • Python: ≥ 3.14.
  • Dependencies: Only the requests package.

There are no restrictions on architecture or OS.

Installation

  1. Obtain the built source bundle for the Pigello Python SDK from here.
  2. Install it in your Python environment with pip:
source my_py_env/bin/activate   # or your env
python -m pip install 'downloads/pigello-sdk.tar.gz'

Usage

Common: attribute values

Attributes on an entity can have one of three kinds of values:

  • None
  • NotSet — Indicates the attribute was deferred or not loaded from the API.
  • A value — Any value allowed by the type of the field.

The NotSet value (from pigello_sdk.fields) means the attribute has not been collected from the API. Both NotSet() and NOT_SET evaluate to false in a boolean context and are equal to each other.

from pigello_sdk.fields import NotSet, NOT_SET

assert bool(NotSet) is bool(NOT_SET) is bool(None) is False
assert NotSet() == NotSet()
assert NOT_SET == NOT_SET

Session: authentication

All communication with the Pigello API through the SDK requires authentication. You provide a session object that handles it.

from pigello_sdk.session import APIUserAgentSession

session: APIUserAgentSession = APIUserAgentSession(
    application_id,
    service_id,
    target_customer_id,
    target_content_type,
    target_object_id,
    integration_user_agent_secret,
    service_version_id,
)

You can verify the session by calling collect_and_set_profile or by accessing the user_agent property. When you access user_agent for the first time, the SDK authenticates with the credentials you provided and stores the profile (including the IntegrationUserAgent entity).

user_agent = session.user_agent
print(user_agent.organization)  # Organization entity connected to the user

Querying data

Most of the time you will want to bulk query data. The QueryHelper is the main tool for this. You can create it manually or via a helper on the entity class you want to query (e.g. Building.get_query_helper(session)).

Add filters and ordering, then run the query to collect data.

from pigello_sdk.query import FILTER_OPERATIONS, FilterInstruction, OrderInstruction
from pigello_sdk.entities.objects.building import Building
from pigello_sdk.entities.objects.realestate import Realestate
from pigello_sdk.fields import NotSet

query_helper = Building.get_query_helper(session)

# Add filters
query_helper.add_filters([
    FilterInstruction("registered_bi_area", FILTER_OPERATIONS.GTE, 500),
    FilterInstruction("name", FILTER_OPERATIONS.IN, ["name1", "name2"]),
])

# Add ordering
query_helper.add_ordering([
    OrderInstruction("registered_bi_area", ascending=False),
    OrderInstruction("registered_usable_area", ascending=True),
])

# Run the query
result = query_helper.collect_query()

# result is QueryResult[Building] — iterable, with metadata
result_list = result.instances  # bulk.EntitiesList (subclass of list)

Relational attributes: When you access a relation (e.g. building.realestate), only the related entity’s id may be set; other attributes can be NotSet until you resolve them. Use resolve_unresolved_relations on the list to load related data in bulk instead of one request per item:

# Only the realestate id may be set; other attributes NotSet
assert isinstance(result_list[0].realestate, Realestate)
assert bool(result_list[0].realestate.id)
assert result_list[0].realestate.name == NotSet

# Resolve the realestate relation for all buildings in the list
result_list.resolve_unresolved_relations(restrict_to_field_names=["realestate"])

# Now realestate attributes are loaded
assert bool(result_list[0].realestate.name)

# Resolve all unresolved relations (or restrict by entity type)
result_list.resolve_unresolved_relations(restrict_to_entity_types=[Realestate])

Best practices

  • Resolve relations in bulk — Prefer resolve_unresolved_relations on lists instead of loading relations one-by-one.
  • Check for NotSet — When reading attributes, remember that deferred/optional fields may be NotSet or None.

Pigello does not guarantee an update lifecycle for this SDK (e.g. new features, deprecations, or bug fixes).

Previous page
 
© Pigello. All rights reserved.