SDK (Python): Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
No edit summary
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{stub|todo=
The Python SDK is a [[Software Development Kit]] written in and for Python, to assist in the creation of connections and interactions with the {{software}} via the [[API]]. It is developed separately from the {{software}}'s internal source code, and is set up with the perspective of the developing end-user in mind.
* 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 {{software}}. It is developed separately from the {{software}}'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 {{software}}, and support for its use falls outside the standard license agreements.'''
'''The Python SDK is a technical supplement for use with the {{software}}, and support for its use falls outside the standard license agreements.'''


==Obtain and use==
==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 Python SDK is offered free and open source on Github. It can be downloaded either using git, or as a direct zipped download. It is available from the following location:
 
https://github.com/Tygron/python-tygronsdk


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 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.
Line 27: Line 23:
'''Note that this file should not be shared with anyone, as the username and password can be derived from it.'''
'''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.
This file should exist in the root of the project folder. It will be loaded in automatically when scripts and examples in the Python SDK are used.


==Structure==
==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 {{software}}. 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 [[Server]]s and/or [[Project Session]]s at once.
{{code|1=
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 {{software}} [[API]]:
* The Base environment requires a username and password to authenticate with the {{software}}, and allows for managing [[User]]s, [[Project]]s, and [[Session]]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 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"
! Type !! Syntax example !! Description
|-
| Connector || <pre>sdk.base.connector</pre> || Facilitates the actual calls to and responses from the {{software}}, including how to specifically authenticate with the environment its related to.
|-
| Events || <pre>tygronsdk.events.io.start(project_name='demo_heat_stress')</pre><pre>tygronsdk.environments.base.data.events.io.start</pre> || Event definitions, which match the various Events which can be sent to the {{software}} to effect interactions.
|-
| Interactions || <pre>sdk.base.sessions.close_project_session(session_id=12345678)</pre><pre>tygronsdk.environments.base.interactions.sessions.close_project_session</pre> || 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 || <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.
|}
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==
The SDK contains a number of examples, which are simple scripts to demonstrate how to leverate the SDK's functionality to perform specific tasks. They are intended to be run simply and without additional input to demonstrate their respective functions, and are commented such that the code can be copied and reused elsewhere. This allows for the examples to serve as simple jumping-off points for development.
The examples can be run directly using commands of the following syntax:
{{code|1=python -m "tygronsdk.examples.basics.users_and_domains"}}


{{article end
{{article end
|seelalso=
|seealso=
*
* [[API]]
* [[SDK (Java)]]
|external=
|external=
* https://github.com/Tygron/python-tygronsdk
* https://github.com/Tygron/python-tygronsdk
}}
}}

Latest revision as of 07:49, 9 July 2024

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 via the API. 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. It is available from the following location:

https://github.com/Tygron/python-tygronsdk

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 scripts and examples in the Python SDK are used.

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

The SDK contains a number of examples, which are simple scripts to demonstrate how to leverate the SDK's functionality to perform specific tasks. They are intended to be run simply and without additional input to demonstrate their respective functions, and are commented such that the code can be copied and reused elsewhere. This allows for the examples to serve as simple jumping-off points for development.

The examples can be run directly using commands of the following syntax:

python -m "tygronsdk.examples.basics.users_and_domains"