SDK (Python): Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 45: Line 45:
* The Session environment requires the [[api token]] of a specific running [[Session]], and allows for all in-session interactions such as importing geo-data, adding and inspecting [[Overlay]]s, and enacting [[Measure]]s.
* The Session environment requires the [[api token]] of a specific running [[Session]], and allows for all in-session interactions such as importing geo-data, adding and inspecting [[Overlay]]s, and enacting [[Measure]]s.


The following are available in the SDK:
The following components are available in the SDK, and can be accessed either directly or (where available) via the implemented helper functions to properly load, process, and use them:
{|class="table sortable overlay"
{|class="table sortable overlay"
! Type !! Syntax example !! Description
! Type !! Syntax example !! Description
Line 57: Line 57:
| Objects || <pre>sdk.base.users.get_my_user()</pre><pre>tygronsdk.environments.base.data.objects.UserData</pre> || Functional datastructures matching specific data request responses from the {{software}}, with helper functions to parse, process, and print the data.
| Objects || <pre>sdk.base.users.get_my_user()</pre><pre>tygronsdk.environments.base.data.objects.UserData</pre> || Functional datastructures matching specific data request responses from the {{software}}, with helper functions to parse, process, and print the data.
|-
|-
| Items || <pre> sdk.session.items.load(tygronsdk.items.Overlay)</pre><pre>tygronsdk.items.Overlay</pre> || Functional datastructures specifically for project data, such as [[Building]]s, [[Overlay]]s, and [[Geo Plugin]]s, with helper functions to parse, process, and print the data.
| Items || <pre>sdk.session.items.load(tygronsdk.items.Overlay)</pre><pre>tygronsdk.items.Overlay</pre> || Functional datastructures specifically for project data, such as [[Building]]s, [[Overlay]]s, and [[Geo Plugin]]s, with helper functions to parse, process, and print the data.
|}
|}


In addition to the components for structuring the interactions and responses to and from the [[API]] of the {{software}}, a number of practical interfaces of functionality are also part of the SDK. These are includes as a jumping-off point from which Notable contents include:


* '''Trigger interface''':  Allows a consistent structure for interactions with the [[API Trigger]] functionality. Any webserver set up to receive [[API Trigger]] requests and forward them to the instantiation of a Trigger implementing this interface, will allow for a multitude of such Triggers to be created with nearly no overhead per additional Trigger.
* '''Template Runner''': Allows for a preloading of data with which to create and run a [[Project]], and export results. Any tool can instantiate, configure, and start a Template Runner, after which the Template Runner will perform all the neccesary steps for a complete, simple Project lifecycle.


==Examples==
==Examples==


{{article end
{{article end

Revision as of 10:14, 21 June 2024

This article is a stub. The following information should be added:
  • Overall structure
  • Running an example
  • How to leverage for development

The Python SDK is a Software Development Kit written in and for Python, to assist in the creation of connections and interactions with the Tygron Platform. It is developed separately from the Tygron Platform's internal source code, and is set up with the perspective of the developing end-user in mind.

The Python SDK is a technical supplement for use with the Tygron Platform, and support for its use falls outside the standard license agreements.

Obtain and use

The Python SDK is offered free and open source on Github. It can be downloaded either using git, or as a direct zipped download.

The module should be a folder named tygronsdk, available for import by the python project in which it is to be used. This can be accomplished by placing the pythonsdk folder in the root of the project folder, the folder containing all the python code of the project the pythonsdk should be used in.

The pythonsdk can then be imported with:

import tygronsdk

Credentials

Because the Tygron Platform requires a valid account, credentials must be provided to authenticate and interact. Credentials can be provided by creating a file named credentials.txt with key-value entries for a username and a password. This will look approximately as follows:

username=
base64_password=YmFzZTY0ZW5jb2RlZHBhc3N3b3Jk

Note that this file should not be shared with anyone, as the username and password can be derived from it.

This file should exist in the root of the project folder. It will be loaded in automatically when the pythonsdk is imported.

Structure

The SDK functions as an importable module with objects and classes intended to alleviate overhead.

The main object is an "sdk" object, which can hold credentials, configuration data, and references to the various interactions possible for the Tygron Platform. It can be instantiated, with data and/or credentials immediately provided to prepare it for whichever workflow it is part of. Multiple instances can co-exist with varying configurations, to allow for interaction with multiple Servers and/or Project Sessions at once.

import tygronsdk
from tygronsdk import sdk as tygron
data = tygronsdk.init.init_data()
sdk = tygron.sdk( data )

The SDK consists of 2 "environments", matching the layers of the Tygron Platform API:

  • The Base environment requires a username and password to authenticate with the Tygron Platform, and allows for managing Users, Projects, and Sessions.
  • The Session environment requires the api token of a specific running Session, and allows for all in-session interactions such as importing geo-data, adding and inspecting Overlays, and enacting Measures.

The following components are available in the SDK, and can be accessed either directly or (where available) via the implemented helper functions to properly load, process, and use them:

Type Syntax example Description
Connector
sdk.base.connector
Facilitates the actual calls to and responses from the Tygron Platform, including how to specifically authenticate with the environment its related to.
Events
tygronsdk.events.io.start(project_name='demo_heat_stress')
tygronsdk.environments.base.data.events.io.start
Event definitions, which match the various Events which can be sent to the Tygron Platform to effect interactions.
Interactions
sdk.base.sessions.close_project_session(session_id=12345678)
tygronsdk.environments.base.interactions.sessions.close_project_session
Prepared, business-logic level functions which encapsulate the low-level calls required (such as individual Events) to perform specific tasks, such as creating a new Project based on a Project Template.
Objects
sdk.base.users.get_my_user()
tygronsdk.environments.base.data.objects.UserData
Functional datastructures matching specific data request responses from the Tygron Platform, with helper functions to parse, process, and print the data.
Items
sdk.session.items.load(tygronsdk.items.Overlay)
tygronsdk.items.Overlay
Functional datastructures specifically for project data, such as Buildings, Overlays, and Geo Plugins, with helper functions to parse, process, and print the data.

In addition to the components for structuring the interactions and responses to and from the API of the Tygron Platform, a number of practical interfaces of functionality are also part of the SDK. These are includes as a jumping-off point from which Notable contents include:

  • Trigger interface: Allows a consistent structure for interactions with the API Trigger functionality. Any webserver set up to receive API Trigger requests and forward them to the instantiation of a Trigger implementing this interface, will allow for a multitude of such Triggers to be created with nearly no overhead per additional Trigger.
  • Template Runner: Allows for a preloading of data with which to create and run a Project, and export results. Any tool can instantiate, configure, and start a Template Runner, after which the Template Runner will perform all the neccesary steps for a complete, simple Project lifecycle.

Examples