Converters¶

Summary¶

`convert_all_coordinates`(results)	Convert coordinate pairs in response items from strings to floats, if valid
`convert_all_place_coordinates`(response)	Convert locations for both standard and community-contributed places to floats
`convert_all_timestamps`(results)	Replace all date/time info with datetime objects, where possible
`convert_csv_list`(obj)	Convert list parameters into an API-compatible (comma-delimited) string
`convert_generic_timestamps`(result)	Replace generic created/updated info that's returned by multiple endpoints.
`convert_histogram`(response)	Convert a response containing time series data into a single `{date: value}` dict
`convert_isoformat`(value)	Convert a date, datetime, or timestamps to a string in ISO 8601 format.
`convert_lat_long`(obj)	Convert a coordinate pair as a dict, list, or string into a pair of floats, if valid
`convert_lat_long_dict`(result)	Convert a coordinate pair dict within a response to floats, if valid
`convert_lat_long_list`(result)	Convert a coordinate pairs in a response item from strings to floats, if valid
`convert_observation_timestamp`(timestamp[, ...])	Convert an observation timestamp + timezone info to a datetime.
`convert_observation_timestamps`(result)	Replace observation date/time info with datetime objects
`convert_offset`(datetime_obj[, tz_offset, ...])	Use timezone offset info to replace a datetime's tzinfo
`ensure_file_obj`(value[, session])	Given a file path or URL, load data into a file-like object
`ensure_list`(value[, convert_csv, delimiter])	Convert an object, response, or (optionally) comma-separated string into a list
`format_dimensions`(dimensions)	Simplify a 'dimensions' dict into a `(width, height)` tuple
`format_file_size`(n_bytes)	Convert a file size in bytes into a human-readable format
`format_license`(value)	Format a Creative Commons license code
`parse_offset`(tz_offset[, tz_name])	Convert a timezone offset string to a tzoffset object, accounting for some common variations in format
`safe_split`(value[, delimiter])	Split a pipe-(or other token)-delimited string
`strip_empty_values`(values)	Remove any dict items with empty or `None` values.
`try_datetime`(timestamp, **kwargs)	Parse a timestamp string into a datetime, if valid; return `None` otherwise
`try_float`(value)	Convert a value to a float, if valid; return `None` otherwise
`try_float_pair`(*values)	Convert a pair of coordinat values to floats, if both are valid; return `None` otherwise
`try_int`(value)	Convert a value to a int, if valid; return `None` otherwise
`try_int_or_float`(value)	Convert a value to either an int or a float, if valid; return `None` otherwise

Module Contents¶

Type conversion utilities

pyinaturalist.converters.convert_all_coordinates(results)¶

Convert coordinate pairs in response items from strings to floats, if valid

Parameters: results (List[Dict[str, Any]]) – Results from API response; expects coordinates in either ‘location’ key or ‘latitude’ and ‘longitude’ keys
Return type: List[Dict[str, Any]]

pyinaturalist.converters.convert_all_place_coordinates(response)¶

Convert locations for both standard and community-contributed places to floats

Return type: Dict[str, Any]

pyinaturalist.converters.convert_all_timestamps(results)¶

Replace all date/time info with datetime objects, where possible

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

pyinaturalist.converters.convert_csv_list(obj)¶

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

Return type: str

pyinaturalist.converters.convert_generic_timestamps(result)¶

Replace generic created/updated info that’s returned by multiple endpoints. Note: Compared to observation timestamps, these are generally more reliable. These seem to be consistently in ISO 8601 format.

Return type: Dict[str, Any]

pyinaturalist.converters.convert_histogram(response)¶

Convert a response containing time series data into a single {date: value} dict

Return type: Dict[Union[date, datetime, int], int]

pyinaturalist.converters.convert_isoformat(value)¶

Convert a date, datetime, or timestamps to a string in ISO 8601 format. If it’s a datetime and doesn’t already have tzinfo, set it to the system’s local timezone.

Raises: dateutil.parser._parser.ParserError –
Return type: str

pyinaturalist.converters.convert_lat_long(obj)¶

Convert a coordinate pair as a dict, list, or string into a pair of floats, if valid

Return type: Optional[Tuple[float, float]]

pyinaturalist.converters.convert_lat_long_dict(result)¶

Convert a coordinate pair dict within a response to floats, if valid

Return type: Dict[str, Any]

pyinaturalist.converters.convert_lat_long_list(result)¶: Convert a coordinate pairs in a response item from strings to floats, if valid

pyinaturalist.converters.convert_observation_timestamp(timestamp, tz_offset=None, tz_name=None, ignoretz=False)¶

Convert an observation timestamp + timezone info to a datetime. This is needed because observed_on and created_at can be in in inconsistent (user-submitted?) formats.

Return type: Optional[datetime]

pyinaturalist.converters.convert_observation_timestamps(result)¶

Replace observation date/time info with datetime objects

Return type: Dict[str, Any]

pyinaturalist.converters.convert_offset(datetime_obj, tz_offset=None, tz_name=None)¶

Use timezone offset info to replace a datetime’s tzinfo

Return type: Optional[datetime]

pyinaturalist.converters.ensure_file_obj(value, session=None)¶

Given a file path or URL, load data into a file-like object

Return type: IO

pyinaturalist.converters.ensure_list(value, convert_csv=False, delimiter=',')¶

Convert an object, response, or (optionally) comma-separated string into a list

Return type: MutableSequence[Any]

pyinaturalist.converters.format_dimensions(dimensions)¶

Simplify a ‘dimensions’ dict into a (width, height) tuple

Return type: Tuple[int, int]

pyinaturalist.converters.format_file_size(n_bytes)¶

Convert a file size in bytes into a human-readable format

Return type: str

pyinaturalist.converters.format_license(value)¶

Format a Creative Commons license code

Return type: Optional[str]

pyinaturalist.converters.parse_offset(tz_offset, tz_name=None)¶

Convert a timezone offset string to a tzoffset object, accounting for some common variations in format

Examples

>>> parse_offset('GMT-08:00', 'PST')
tzoffset('PST', -28800)
>>> parse_offset('-06:00')
tzoffset(None, -21600)
>>> parse_offset('+05:30')
tzoffset(None, 19800)
>>> parse_offset('0530')
tzoffset(None, 19800)