Python API

The faas_client package lets you submit FAAS calculations, monitor their progress, and fetch their results.

import faas_client as fc

calc

calc(
    config: dict,
    quiet: bool = False,
    faas_url: str | None = None,
    faas_token: str | None = None,
    batch: bool = True,
    type_: str = 'features',
    auto_raise: bool = False,
) -> pandas.DataFrame

Calculates the specified features.

The function accepts a FAAS config and a user token, and returns the result as a pandas.DataFrame. A tqdm progress bar is shown during the calculation.

Parameters

Name	Type	Description	Default
config	dict	FAAS config.	—
quiet	bool	If True, do not print progress information to the console.	False
faas_url	str | None	FAAS service URL. If omitted, it is read from the FAAS_URL environment variable.	None
faas_token	str | None	FAAS user token. If omitted, it is read from the FAAS_TOKEN environment variable.	None
batch	bool	If True, automatically split a large config into batches. Batching is not used when points are passed as a list.	True
type_	str	Calculation type.	'features'
auto_raise	bool	If True, raise an exception when the calculation finishes with errors.	False

Returns

Type	Description
pandas.DataFrame	The calculated features.

Example

import faas_client as fc

config = {
    'points': [
        {
            'id': 1,
            'geopos': {
                'type': 'Point',
                'coordinates': [30.33, 59.86],
            },
        },
    ],
    'features': {
        'apartments_foot_10min': {
            'type': 'isochrone',
            'dataset': 'ru-pub-households/apartments',
            'metric': 'foot',
            'limit': 10,
            'field': 'apartments',
            'agg': 'sum',
        },
    },
}

df = fc.calc(config, faas_token='token')

submit

submit(
    config: dict,
    quiet: bool = False,
    url: str | None = None,
    token: str | None = None,
    type_: str = 'features',
    session: requests.Session | None = None,
) -> str

Submits a feature calculation job.

Parameters

Name	Type	Description	Default
config	dict	FAAS config.	—
quiet	bool	If True, do not print the job ID to the console.	False
url	str | None	FAAS service URL. If omitted, it is read from the FAAS_URL environment variable.	None
token	str | None	FAAS user token. If omitted, it is read from the FAAS_TOKEN environment variable.	None
type_	str	Calculation type.	'features'
session	requests.Session | None	Client HTTP session.	None

Returns

Type	Description
str	ID of the submitted calculation job. Use it to check the job status and fetch the result.

wait

wait(
    job_id: str,
    quiet: bool = False,
    url: str | None = None,
    token: str | None = None,
    type_: str = 'features',
    fetch_result: bool = True,
    session: requests.Session | None = None,
) -> dict

Waits until a feature calculation job is complete.

While waiting, it shows a tqdm progress bar that is updated once per second. After the job is complete, it returns the result and status.

Parameters

Name	Type	Description	Default
job_id	str	ID of the submitted job.	—
quiet	bool	If True, do not print progress information to the console.	False
url	str | None	FAAS service URL. If omitted, it is read from the FAAS_URL environment variable.	None
token	str | None	FAAS user token. If omitted, it is read from the FAAS_TOKEN environment variable.	None
type_	str	Calculation type.	'features'
fetch_result	bool	If False, return only the status without the calculation result.	True
session	requests.Session | None	Client HTTP session.	None

Returns

Type	Description
dict	The job status and, if fetch_result=True, the calculation result.

fetch

fetch(
    job_id: str,
    url: str | None = None,
    token: str | None = None,
    fetch_result: bool = True,
    session: requests.Session | None = None,
)

Gets the result and status of a feature calculation job. If the result is not ready, returns the current status and an empty result.

Parameters

Name	Type	Description	Default
job_id	str	ID of the submitted job.	—
url	str | None	FAAS service URL. If omitted, it is read from the FAAS_URL environment variable.	None
token	str | None	FAAS user token. If omitted, it is read from the FAAS_TOKEN environment variable.	None
fetch_result	bool	If False, return only the status without the calculation result.	True
session	requests.Session | None	Client HTTP session.	None

Returns

Type	Description
dict	The job status and result. The result field contains a list of objects with the calculated features.

abort

abort(
    job_id: str,
    url: str | None = None,
    token: str | None = None,
    session: requests.Session | None = None,
)

Aborts a running feature calculation job.

Aborting is not immediate: points that have already started are completed, while the remaining points are not calculated. When the job finishes, a partial result becomes available and only successfully calculated features are deducted from the balance.

Parameters

Name	Type	Description	Default
job_id	str	ID of the submitted job.	—
url	str | None	FAAS service URL. If omitted, it is read from the FAAS_URL environment variable.	None
token	str | None	FAAS user token. If omitted, it is read from the FAAS_TOKEN environment variable.	None
session	requests.Session | None	Client HTTP session.	None

Returns

Type	Description
dict	Service response containing the job abortion message.