Getting Started With Python

Python

We support Python 3.7 or later. This guide assumes that you've already installed Python and that it's on your path.

Run this command in Command Prompt or other shell to check that Python is installed correctly:

python --version

It is not possible to use the API with IronPython.

See Installing Prerequisites Without Admin Rights if you need to install Python without admin rights on a Windows PC.

.NET Runtime

The API requires the runtime for .NET Core 3.1.

If you don't have the correct runtime you'll see an error which includes:

"The framework 'Microsoft.NETCore.App', version '3.1.0' was not found."

For more help see Troubleshooting .NET.

Python Package

The API is available as a Python package, distributed on PyPI (The Python Package Index).

Installation

You can use Python's package manager pip to install the API from the command line using the command below.

python -m pip install <package name>

For example, to install the AdSec API the command would be:

python -m pip install oasys.adsec

You may need to run this command with Administrator rights unless you're using a virtual environment.

Please see the Python documentation for more information about Pip and python packages.

Code Samples

The Oasys API Samples project contains working examples. We suggest you clone the whole repository to your local computer and check that you can run one of the examples before creating your own API project.

git clone https://github.com/arup-group/oasys-api-samples.git

Example

This simple example displays the AdSec API version.

# Load the .NET Core API using PythonNet
import oasys.adsec

# Import the features we need
from Oasys.AdSec import IVersion

if __name__ == '__main__':
    print('This AdSec API version is ' + IVersion.Api())

Python and Type Casting

The API interface is strongly typed. When you call API methods from Python you must be sure to pass the right type of object. For example, you cannot pass an int when a double is required.

In C# and other .NET languages you can use 'casts' to convert from one type to another. In some cases, items are cast automatically.

This is particularly noticeable with OasysUnits as it uses a lot of automatic casts. Consider this example in C#.

    width = OasysUnits.Length.FromMeters(3);

This doesn't work in Python because the argument to FromMeters is actually an instance of OasysUnits.QuantityValue.

PythonNetHelpers

We've provided PythonNetHelpers.dll to solve this problem. The TypeHelpers.Cast method will attempt to cast a value to a target type. It will search for and use implicit converters if there are any. This allows FromMeters to be called like this:

from PythonNetHelpers import TypeHelpers
...
    width = Length.FromMeters(TypeHelpers.Cast[QuantityValue](2))

You can avoid the cast altogether by calling OasysUnits constructors directly. e.g.

    area = OasysUnits.Area(15.0, OasysUnits.Units.AreaUnit.SquareMeter)

PythonNetHelpers.dll is included in the API distribution and api.py loads it automatically so there's nothing else you need to do to use it if you use api.py.