pygplates.FeaturesFunctionArgument

class pygplates.FeaturesFunctionArgument

Bases: Boost.Python.instance

A utility class for extracting features from collections and files.

This is useful when defining your own function that accepts features from a variety of sources. It avoids the hassle of having to explicitly test for each source type.

The currently supported source types are:

FeatureCollection
filename (string)
Feature
sequence of Feature
sequence of any combination of the above four types

The following is an example of a user-defined function that accepts features in any of the above forms:

def my_function(features):
    # Turn function argument into something more convenient for extracting features.
    features = pygplates.FeaturesFunctionArgument(features)

    # Iterate over features from the function argument.
    for feature in features.get_features()
        ...

# Some examples of calling the above function:
my_function('file.gpml')
my_function(['file1.gpml', 'file2.gpml'])
my_function(['file.gpml', feature_collection])
my_function([feature1, feature2])
my_function([feature_collection,  feature1, feature2 ])
my_function([feature_collection, [feature1, feature2]])
my_function(feature)

__init__(function_argument)

Extract features from files and/or collections of features.

Parameters: function_argument (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – A feature collection, or filename, or feature, or sequence of features, or a sequence (eg, list or tuple) of any combination of those four types
Raises: OpenFileForReadingError if any file is not readable (when filenames specified)
Raises: FileFormatNotSupportedError if any file format (identified by the filename extensions) does not support reading (when filenames specified)

The features are extracted from function_argument.

If any filenames are specified (in function_argument) then this method uses FeatureCollection internally to read those files. Those files contain the subset of features returned by get_files().

To turn an argument of your function into a list of features:

def my_function(features):
    # Turn function argument into something more convenient for extracting features.
    features = pygplates.FeaturesFunctionArgument(features)

    # Iterate over features from the function argument.
    for feature in features.get_features()
        ...

my_function(['file1.gpml', 'file2.gpml'])

Methods

`__init__`(function_argument)	Extract features from files and/or collections of features.
`contains_features`(function_argument)	[staticmethod] Return whether function_argument contains features.
`get_features`()	Returns a list of all features specified in the `constructor`.
`get_files`()	Returns a list of feature collections that were loaded from files specified in the `constructor`.

static contains_features(function_argument)

[staticmethod] Return whether function_argument contains features.

Parameters: function_argument – the function argument to test for features

This method returns True if function_argument is a feature collection, or filename, or feature, or sequence of features, or a sequence (eg, list or tuple) of any combination of those four types.

To define a function that raises TypeError if its function argument does not contain features:

def my_function(features):
    if not pygplates.FeaturesFunctionArgument.contains_features(features):
        raise TypeError("Unexpected type for argument 'features' in function 'my_function'.")

    # Turn function argument into something more convenient for extracting features.
    features = pygplates.FeaturesFunctionArgument(features)
    ...

Note that it is not necessary to call contains_features() before constructing a FeaturesFunctionArgument because the constructor will raise an error if the function argument does not contain features. However raising your own error (as in the example above) helps to clarify the source of the error for the user (caller) of your function.

get_features()

Returns a list of all features specified in the constructor.

Return type: list of Feature

Note that any features coming from files are loaded only once in the constructor. They are not loaded each time this method is called.

Define a function that extract features and processes them:

def my_function(features):
    # Turn function argument into something more convenient for extracting features.
    features = pygplates.FeaturesFunctionArgument(features)

    # Iterate over features from the function argument.
    for feature in features.get_features():
        ...

# Process features in 'file.gpml', 'feature_collection' and 'feature'.
my_function(['file.gpml', feature_collection, feature])

get_files()

Returns a list of feature collections that were loaded from files specified in the constructor.

Returns: a list of (feature collection, filename) tuples
Return type: list of (FeatureCollection, string) tuples

Only those feature collections associated with filenames (specified in the function argument in constructor) are returned. Features and feature collections that were directly specified (in the function argument in constructor) are not returned here.

Note that the returned features (coming from files) are loaded only once in the constructor. They are not loaded each time this method is called.

Define a function that extract features, modifies them and writes those features that came from files back out to those same files:

def my_function(features):
    # Turn function argument into something more convenient for extracting features.
    features = pygplates.FeaturesFunctionArgument(features)

    # Modify features in some way.
    for feature in features.get_features():
        ...

    # Write those (modified) feature collections that came from files (if any) back to file.
    files = features.get_files()
    if files:
        for feature_collection, filename in files:
            # This can raise pygplates.OpenFileForWritingError if file is not writable.
            feature_collection.write(filename)

# Modify features in 'file.gpml' and 'feature_collection'.
# Modified features from 'file.gpml' will get written back out to 'file.gpml'.
my_function(['file.gpml', feature_collection])