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_field_params`(params)	Translate simplified format of observation field values into API-compatible format
`convert_observation_params`(params)	Some common parameter conversions needed by observation CRUD endpoints
`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[, ...])	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)¶

Convert any boolean request parameters to javascript-style boolean strings

Return type:: Dict[str, Any]

pyinaturalist.request_params.convert_datetime_params(params)¶

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)¶

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)¶

Convert observation field filters from simplified format to full request params

Return type:: Dict[str, Any]

pyinaturalist.request_params.convert_observation_field_params(params)¶

Translate simplified format of observation field values into API-compatible format

Return type:: Dict[str, Any]

pyinaturalist.request_params.convert_observation_params(params)¶: Some common parameter conversions needed by observation CRUD endpoints

pyinaturalist.request_params.convert_pagination_params(params)¶

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)¶

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=None, allow_str_ids=False)¶

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)¶

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

Parameters:

start (Union[date, datetime, str]) – Start date or string (inclusive)
end (Union[date, datetime, str]) – End date or string (inclusive)
interval (Union[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)¶

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

Return type:: Dict

pyinaturalist.request_params.normalize_rank(rank)¶

Normalize and validate a taxonomic rank, alias, or abbreviation

Return type:: str

pyinaturalist.request_params.normalize_rank_params(params)¶

Normalize any taxonomic ranks in request params

Return type:: Dict[str, Any]

pyinaturalist.request_params.preprocess_request_body(body)¶

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

Return type:: Optional[Dict[str, Any]]

pyinaturalist.request_params.preprocess_request_params(params, convert_lists=True)¶

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

Return type:: Dict[str, Any]

pyinaturalist.request_params.split_common_params(params)¶

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)¶

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)¶

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)¶

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