pyinaturalist.request_params¶

Summary¶

`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_fields`(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
`get_interval_ranges`(start_date, end_date[, …])	Get a list of date ranges between `start_date` and `end_date` with the specified interval .
`is_int_list`(values)	Determine if a value contains one or more valid integers
`prepare_request`(url[, access_token, …])	Translate some `pyinaturalist`-specific params into standard params and headers, and other request param preprocessing.
`preprocess_request_body`(body)	Perform type conversions, sanity checks, etc.
`preprocess_request_params`(params)	Perform type conversions, sanity checks, etc.
`validate_ids`(ids)	Ensure ID(s) are all valid integers, and convert to a comma-delimited string if multiple
`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.

Details¶

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]

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_fields(params)¶

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

Return type: 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]

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.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_list(values)¶

Determine if a value contains one or more valid integers

Return type: bool

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

Translate some pyinaturalist-specific params into standard params and headers, and other request param preprocessing. This is made non-requests-specific so it could potentially be reused for aiohttp requests.

Return type: Tuple[str, Dict[str, Any], Dict, Optional[Dict]]
Returns: Tuple of (URL, params, headers, data)

pyinaturalist.request_params.preprocess_request_body(body)¶

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

Return type: Dict[str, Any]

pyinaturalist.request_params.preprocess_request_params(params)¶

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

Return type: 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

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