pyinaturalist.request_params module

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 request parameters, along with request validation that makes debugging easier.

pyinaturalist.request_params.convert_bool_params(params)

Convert any boolean request parameters to javascript-style boolean strings

Return type

Dict[str, Any]

Parameters

params (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]

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.convert_list(obj)

Convert list parameters into an API-compatible (comma-delimited) string

Return type

str

Parameters

obj (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]

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.convert_observation_fields(params)

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

Return type

Dict[str, Any]

Parameters

params (Dict[str, Any]) –

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]

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.ensure_file_obj(photo)

Given a file objects or path, read it into a file-like object if it’s a path

Return type

BinaryIO

Parameters

photo (Union[BinaryIO, str]) –

pyinaturalist.request_params.ensure_file_objs(photos)

Given one or more file objects and/or paths, read any paths into a file-like object

Return type

Iterable[BinaryIO]

Parameters

photos (Iterable[Union[BinaryIO, str]]) –

pyinaturalist.request_params.ensure_list(values)

If the value is a string or comma-separated list of values, convert it into a list

Parameters

values (Any) –

pyinaturalist.request_params.get_interval_ranges(start_date, end_date, interval='monthly')

Get a list of date ranges between start_date and end_date with the specified interval .. rubric:: Example

>>> # Get date ranges representing months of a year
>>> get_interval_ranges(datetime(2020, 1, 1), datetime(2020, 12, 31), 'monthly')

Parameters

• start_date (datetime) – Starting date of date ranges (inclusive)

• end_date (datetime) – End date of date ranges (inclusive)

• interval – Either ‘monthly’ or ‘yearly’

Returns

[(start_date, end_date), (start_date, end_date), ...]

Return type

List of date ranges in the format

pyinaturalist.request_params.is_int(value)

Determine if a value is a valid integer

Return type

bool

Parameters

value (Any) –

pyinaturalist.request_params.is_int_list(values)

Determine if a value contains one or more valid integers

Return type

bool

Parameters

values (Any) –

pyinaturalist.request_params.is_valid_multiple_choice_option(value, choices)

Determine if a multiple-choice request parameter contains valid value(s).

Return type

bool

Parameters

• value (Any) –

• choices (Iterable) –

pyinaturalist.request_params.prepare_request(url, access_token=None, user_agent=None, ids=None, params=None, headers=None)

Translate some pyinaturalist-specific params into standard requests params and headers, and other request param preprocessing

Return type

Tuple[str, Dict[str, Any], Dict]

Returns

Tuple of (URL, params, headers)

Parameters

• url (str) –

• access_token (Optional[str]) –

• user_agent (Optional[str]) –

• ids (Optional[Union[int, List[int]]]) –

• params (Optional[Dict[str, Any]]) –

• headers (Optional[Dict]) –

pyinaturalist.request_params.preprocess_request_params(params)

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

Return type

Dict[str, Any]

Parameters

params (Optional[Dict[str, Any]]) –

pyinaturalist.request_params.strip_empty_params(params)

Remove any request parameters with empty or None values.

Return type

Dict[str, Any]

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.translate_rank_range(params)

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

Return type

Dict[str, Any]

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.validate_ids(ids)

Ensure ID(s) are all valid integers, and convert to a comma-delimited string if multiple

Raises

ValueError –

Return type

str

Parameters

ids (Any) –

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 –

Parameters

• params (Dict[str, Any]) –

• key (str) –

• choices (Iterable) –

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

Parameters

params (Dict[str, Any]) –

pyinaturalist.request_params.warn(msg)