Request Params¶

Summary¶

Classes

Functions

`convert_bool_params`(params)	Convert any boolean request parameters to javascript-style boolean strings
`convert_datetime_params`(params)	Convert any dates, datetimes, or timestamps in other formats into ISO 8601 strings.
`convert_list_params`(params)	Convert any list parameters into an API-compatible (comma-delimited) string.
`convert_observation_field_filters`(params)	Convert observation field filters from simplified format to full request params
`convert_observation_params`(params)	Some common parameter conversions needed by observation CRUD endpoints
`convert_observation_params_v2`(params)	Some common parameter conversions needed by observation CRUD endpoints; same as convert_observation_params but splits out observation field values.
`convert_ofv_params`(params)	Translate simplified format of observation field values into API-compatible format.
`convert_pagination_params`(params)	Allow `count_only=True` as a slightly more intuitive shortcut to only get a count of results
`convert_rank_range`(params)	If min and/or max rank is specified in params, translate into a list of ranks
`convert_url_ids`(url, ids, allow_str_ids)	If one or more resources are requested by ID, validate and update the request URL accordingly
`get_interval_ranges`(start, end, interval)	Given a date range and a time interval, split the range into a list of smaller ranges
`get_valid_kwargs`(func, kwargs)	Get the subset of non-None `kwargs` that are valid params for `func`
`normalize_rank`(rank)	Normalize and validate a taxonomic rank, alias, or abbreviation
`normalize_rank_params`(params)	Normalize any taxonomic ranks in request params
`preprocess_request_body`(body)	Perform type conversions, sanity checks, etc.
`preprocess_request_params`(params, convert_lists)	Perform type conversions, sanity checks, etc.
`split_common_params`(params)	Split out common keyword args (for pyinaturalist functions) from request params (for API)
`strip_empty_values`(values)	Remove any dict items with empty or `None` values.
`validate_multiple_choice_param`(params, key, ...)	Verify that a multiple-choice request parameter contains valid value(s); if not, raise an error.
`validate_multiple_choice_params`(params)	Verify that multiple-choice request parameters contain a valid value.

Module Contents¶

Helper functions for processing and validating request parameters. The main purpose of these functions is to support some python-specific conveniences and translate them into standard API request parameters, along with client-side request validation.

Also see pyinaturalist.converters for type conversion utilities not specific to request params.

pyinaturalist.request_params.convert_bool_params(params) → dict[str, Any]¶

Convert any boolean request parameters to javascript-style boolean strings

Return type:: dict[str, Any]

pyinaturalist.request_params.convert_datetime_params(params) → dict[str, Any]¶

Convert any dates, datetimes, or timestamps in other formats into ISO 8601 strings.

API behavior note: params that take date but not time info will accept a full timestamp and just ignore the time, so it’s safe to parse both date and datetime strings into timestamps

Raises:: dateutil.parser._parser.ParserError –
Return type:: dict[str, Any]

pyinaturalist.request_params.convert_list_params(params) → dict[str, Any]¶

Convert any list parameters into an API-compatible (comma-delimited) string. Will be url-encoded by requests. For example: [‘k1’, ‘k2’, ‘k3’] -> k1%2Ck2%2Ck3

Return type:: dict[str, Any]

pyinaturalist.request_params.convert_observation_field_filters(params) → dict[str, Any]¶

Convert observation field filters from simplified format to full request params

Return type:: dict[str, Any]

pyinaturalist.request_params.convert_observation_params(params) → tuple[list, list, list, dict[str, Any], dict[str, Any]]¶

Some common parameter conversions needed by observation CRUD endpoints

Return type:: tuple[list, list, list, dict[str, Any], dict[str, Any]]

pyinaturalist.request_params.convert_observation_params_v2(params) → tuple[list, list, list, list, dict[str, Any], dict[str, Any]]¶

Some common parameter conversions needed by observation CRUD endpoints; same as convert_observation_params but splits out observation field values.

Return type:: tuple[list, list, list, list, dict[str, Any], dict[str, Any]]

pyinaturalist.request_params.convert_ofv_params(params) → list[dict]¶

Translate simplified format of observation field values into API-compatible format. Also handles an already API-compatible format.

Return type:: list[dict]

pyinaturalist.request_params.convert_pagination_params(params) → dict[str, Any]¶

Allow count_only=True as a slightly more intuitive shortcut to only get a count of results

Return type:: dict[str, Any]

pyinaturalist.request_params.convert_rank_range(params) → dict[str, Any]¶

If min and/or max rank is specified in params, translate into a list of ranks

Return type:: dict[str, Any]

pyinaturalist.request_params.convert_url_ids(url, ids, allow_str_ids) → str¶

If one or more resources are requested by ID, validate and update the request URL accordingly

Return type:: str

pyinaturalist.request_params.get_interval_ranges(start, end, interval) → list[tuple[date | datetime, date | datetime]]¶

Given a date range and a time interval, split the range into a list of smaller ranges

Parameters:

start (date | datetime | str) – Start date or string (inclusive)
end (date | datetime | str) – End date or string (inclusive)
interval (str | timedelta | relativedelta) – Time interval (delta or alias: ‘hour’, ‘day’, ‘month’, or ‘year’)

Returns:

[(start_date, end_date), ...]

Return type:

List of date ranges of size interval, in the format

pyinaturalist.request_params.get_valid_kwargs(func, kwargs) → dict¶

Get the subset of non-None kwargs that are valid params for func

Return type:: dict

pyinaturalist.request_params.normalize_rank(rank) → str¶

Normalize and validate a taxonomic rank, alias, or abbreviation

Return type:: str

pyinaturalist.request_params.normalize_rank_params(params) → dict[str, Any]¶

Normalize any taxonomic ranks in request params

Return type:: dict[str, Any]

pyinaturalist.request_params.preprocess_request_body(body) → dict[str, Any] | None¶

Perform type conversions, sanity checks, etc. on JSON-formatted request body

Return type:: dict[str, Any] | None

pyinaturalist.request_params.preprocess_request_params(params, convert_lists) → dict[str, Any]¶

Perform type conversions, sanity checks, etc. on request parameters

Return type:: dict[str, Any]

pyinaturalist.request_params.split_common_params(params) → tuple[dict[str, Any], dict[str, Any]]¶

Split out common keyword args (for pyinaturalist functions) from request params (for API)

Return type:: tuple[dict[str, Any], dict[str, Any]]

pyinaturalist.request_params.strip_empty_values(values) → dict¶

Remove any dict items with empty or None values. Observation field filters are an exception (e.g. field:foo=).

Return type:: dict

pyinaturalist.request_params.validate_multiple_choice_param(params, key, choices) → dict[str, Any]¶

Verify that a multiple-choice request parameter contains valid value(s); if not, raise an error. Used for endpoint-specific params.

Return type:: dict[str, Any]
Returns:: Parameters with modifications (if any)
Raises:: ValueError –

pyinaturalist.request_params.validate_multiple_choice_params(params) → dict[str, Any]¶

Verify that multiple-choice request parameters contain a valid value.

Note: This does not check endpoint-specific params, i.e., those that have the same name but different values across different endpoints.

Return type:: dict[str, Any]
Returns:: Parameters with modifications (if any)
Raises:: ValueError – Error message will contain info on all validation errors, if there are multiple