Module: ncbi.datasets.openapi.model_utils

NCBI Datasets API

Module: ncbi.datasets.openapi.model_utils

NCBI Datasets API

### NCBI Datasets is a resource that lets you easily gather data from NCBI. The Datasets API is still in alpha, and we’re updating it often to add new functionality, iron out bugs and enhance usability. For some larger downloads, you may want to download a [dehydrated bag](https://0-www-ncbi-nlm-nih-gov.brum.beds.ac.uk/datasets/docs/rehydrate/), and retrieve the individual data files at a later time. # noqa: E501

The version of the OpenAPI document: v1 Generated by: https://openapi-generator.tech

ncbi.datasets.openapi.model_utils.convert_js_args_to_python_args(fn)
class ncbi.datasets.openapi.model_utils.cached_property(fn)

Bases: object

result_key = '_results'
ncbi.datasets.openapi.model_utils.allows_single_value_input(cls)

This function returns True if the input composed schema model or any descendant model allows a value only input This is true for cases where oneOf contains items like: oneOf:

  • float

  • NumberWithValidation

  • StringEnum

  • ArrayModel

  • null

TODO: lru_cache this

ncbi.datasets.openapi.model_utils.composed_model_input_classes(cls)

This function returns a list of the possible models that can be accepted as inputs. TODO: lru_cache this

class ncbi.datasets.openapi.model_utils.OpenApiModel(*args, **kwargs)

Bases: object

The base class for all OpenAPIModels

set_attribute(name, value)
class ncbi.datasets.openapi.model_utils.ModelSimple(*args, **kwargs)

Bases: ncbi.datasets.openapi.model_utils.OpenApiModel

the parent class of models whose type != object in their swagger/openapi

get(name, default=None)

returns the value of an attribute or some default value if the attribute was not set

to_str()

Returns the string representation of the model

class ncbi.datasets.openapi.model_utils.ModelNormal(*args, **kwargs)

Bases: ncbi.datasets.openapi.model_utils.OpenApiModel

the parent class of models whose type == object in their swagger/openapi

get(name, default=None)

returns the value of an attribute or some default value if the attribute was not set

to_dict()

Returns the model properties as a dict

to_str()

Returns the string representation of the model

class ncbi.datasets.openapi.model_utils.ModelComposed(*args, **kwargs)

Bases: ncbi.datasets.openapi.model_utils.OpenApiModel

the parent class of models whose type == object in their swagger/openapi and have oneOf/allOf/anyOf

When one sets a property we use var_name_to_model_instances to store the value in the correct class instances + run any type checking + validation code. When one gets a property we use var_name_to_model_instances to get the value from the correct class instances. This allows multiple composed schemas to contain the same property with additive constraints on the value.

_composed_schemas (dict) stores the anyOf/allOf/oneOf classes key (str): allOf/oneOf/anyOf value (list): the classes in the XOf definition.

Note: none_type can be included when the openapi document version >= 3.1.0

_composed_instances (list): stores a list of instances of the composed schemas defined in _composed_schemas. When properties are accessed in the self instance, they are returned from the self._data_store or the data stores in the instances in self._composed_schemas _var_name_to_model_instances (dict): maps between a variable name on self and the composed instances (self included) which contain that data key (str): property name value (list): list of class instances, self or instances in _composed_instances which contain the value that the key is referring to.

get(name, default=None)

returns the value of an attribute or some default value if the attribute was not set

to_dict()

Returns the model properties as a dict

to_str()

Returns the string representation of the model

ncbi.datasets.openapi.model_utils.get_simple_class(input_value)

Returns an input_value’s simple class that we will use for type checking Python2: float and int will return int, where int is the python3 int backport str and unicode will return str, where str is the python3 str backport Note: float and int ARE both instances of int backport Note: str_py2 and unicode_py2 are NOT both instances of str backport

Parameters

input_value (class/class_instance) – the item for which we will return the simple class

ncbi.datasets.openapi.model_utils.check_allowed_values(allowed_values, input_variable_path, input_values)

Raises an exception if the input_values are not allowed

Parameters
  • allowed_values (dict) – the allowed_values dict

  • input_variable_path (tuple) – the path to the input variable

  • input_values (list/str/int/float/date/datetime) – the values that we are checking to see if they are in allowed_values

ncbi.datasets.openapi.model_utils.is_json_validation_enabled(schema_keyword, configuration=None)

Returns true if JSON schema validation is enabled for the specified validation keyword. This can be used to skip JSON schema structural validation as requested in the configuration.

Parameters
  • schema_keyword (string) – the name of a JSON schema validation keyword.

  • configuration (Configuration) – the configuration class.

ncbi.datasets.openapi.model_utils.check_validations(validations, input_variable_path, input_values, configuration=None)

Raises an exception if the input_values are invalid

Parameters
  • validations (dict) – the validation dictionary.

  • input_variable_path (tuple) – the path to the input variable.

  • input_values (list/str/int/float/date/datetime) – the values that we are checking.

  • configuration (Configuration) – the configuration class.

ncbi.datasets.openapi.model_utils.order_response_types(required_types)

Returns the required types sorted in coercion order

Parameters

required_types (list/tuple) – collection of classes or instance of list or dict with class information inside it.

Returns

coercion order sorted collection of classes or instance

of list or dict with class information inside it.

Return type

(list)

ncbi.datasets.openapi.model_utils.remove_uncoercible(required_types_classes, current_item, spec_property_naming, must_convert=True)

Only keeps the type conversions that are possible

Parameters
  • required_types_classes (tuple) – tuple of classes that are required these should be ordered by COERCION_INDEX_BY_TYPE

  • spec_property_naming (bool) – True if the variable names in the input data are serialized names as specified in the OpenAPI document. False if the variables names in the input data are python variable names in PEP-8 snake case.

  • current_item (any) – the current item (input data) to be converted

Keyword Arguments

must_convert (bool) – if True the item to convert is of the wrong type and we want a big list of coercibles if False, we want a limited list of coercibles

Returns

the remaining coercible required types, classes only

Return type

(list)

ncbi.datasets.openapi.model_utils.get_discriminated_classes(cls)

Returns all the classes that a discriminator converts to TODO: lru_cache this

ncbi.datasets.openapi.model_utils.get_possible_classes(cls, from_server_context)
ncbi.datasets.openapi.model_utils.get_required_type_classes(required_types_mixed, spec_property_naming)

Converts the tuple required_types into a tuple and a dict described below

Parameters
  • required_types_mixed (tuple/list) – will contain either classes or instance of list or dict

  • spec_property_naming (bool) – if True these values came from the server, and we use the data types in our endpoints. If False, we are client side and we need to include oneOf and discriminator classes inside the data types in our endpoints

Returns

valid_classes (tuple): the valid classes that the current item

should be

dict_valid_class_to_child_types_mixed (dict):

valid_class (class): this is the key child_types_mixed (list/dict/tuple): describes the valid child

types

Return type

(valid_classes, dict_valid_class_to_child_types_mixed)

ncbi.datasets.openapi.model_utils.change_keys_js_to_python(input_dict, model_class)

Converts from javascript_key keys in the input_dict to python_keys in the output dict using the mapping in model_class. If the input_dict contains a key which does not declared in the model_class, the key is added to the output dict as is. The assumption is the model_class may have undeclared properties (additionalProperties attribute in the OAS document).

ncbi.datasets.openapi.model_utils.get_type_error(var_value, path_to_item, valid_classes, key_type=False)
ncbi.datasets.openapi.model_utils.deserialize_primitive(data, klass, path_to_item)

Deserializes string to primitive type.

Parameters
  • data – str/int/float

  • klass – str/class the class to convert to

Returns

int, float, str, bool, date, datetime

ncbi.datasets.openapi.model_utils.get_discriminator_class(model_class, discr_name, discr_value, cls_visited)

Returns the child class specified by the discriminator.

Parameters
  • model_class (OpenApiModel) – the model class.

  • discr_name (string) – the name of the discriminator property.

  • discr_value (any) – the discriminator value.

  • cls_visited (list) – list of model classes that have been visited. Used to determine the discriminator class without visiting circular references indefinitely.

Returns

the chosen child class that will be used

to deserialize the data, for example dog.Dog. If a class is not found, None is returned.

Return type

used_model_class (class/None)

ncbi.datasets.openapi.model_utils.deserialize_model(model_data, model_class, path_to_item, check_type, configuration, spec_property_naming)

Deserializes model_data to model instance.

Parameters
  • model_data (int/str/float/bool/none_type/list/dict) – data to instantiate the model

  • model_class (OpenApiModel) – the model class

  • path_to_item (list) – path to the model in the received data

  • check_type (bool) – whether to check the data tupe for the values in the model

  • configuration (Configuration) – the instance to use to convert files

  • spec_property_naming (bool) – True if the variable names in the input data are serialized names as specified in the OpenAPI document. False if the variables names in the input data are python variable names in PEP-8 snake case.

Returns

model instance

Raises
ncbi.datasets.openapi.model_utils.deserialize_file(response_data, configuration, content_disposition=None)

Deserializes body to file

Saves response body into a file in a temporary folder, using the filename from the Content-Disposition header if provided.

Parameters
  • response_data (param) – the file data to write

  • configuration (Configuration) – the instance to use to convert files

Keyword Arguments

content_disposition (str) – the value of the Content-Disposition header

Returns

the deserialized file which is open

The user is responsible for closing and reading the file

Return type

(file_type)

ncbi.datasets.openapi.model_utils.attempt_convert_item(input_value, valid_classes, path_to_item, configuration, spec_property_naming, key_type=False, must_convert=False, check_type=True)
Parameters
  • input_value (any) – the data to convert

  • valid_classes (any) – the classes that are valid

  • path_to_item (list) – the path to the item to convert

  • configuration (Configuration) – the instance to use to convert files

  • spec_property_naming (bool) – True if the variable names in the input data are serialized names as specified in the OpenAPI document. False if the variables names in the input data are python variable names in PEP-8 snake case.

  • key_type (bool) – if True we need to convert a key type (not supported)

  • must_convert (bool) – if True we must convert

  • check_type (bool) – if True we check the type or the returned data in ModelComposed/ModelNormal/ModelSimple instances

Returns

instance (any) the fixed item

Raises
ncbi.datasets.openapi.model_utils.is_type_nullable(input_type)

Returns true if None is an allowed value for the specified input_type.

A type is nullable if at least one of the following conditions is true: 1. The OAS ‘nullable’ attribute has been specified, 1. The type is the ‘null’ type, 1. The type is a anyOf/oneOf composed schema, and a child schema is

the ‘null’ type.

Parameters

input_type (type) – the class of the input_value that we are checking

Returns

bool

ncbi.datasets.openapi.model_utils.is_valid_type(input_class_simple, valid_classes)
Parameters
  • input_class_simple (class) – the class of the input_value that we are checking

  • valid_classes (tuple) – the valid classes that the current item should be

Returns

bool

ncbi.datasets.openapi.model_utils.validate_and_convert_types(input_value, required_types_mixed, path_to_item, spec_property_naming, _check_type, configuration=None)

Raises a TypeError is there is a problem, otherwise returns value

Parameters
  • input_value (any) – the data to validate/convert

  • required_types_mixed (list/dict/tuple) – A list of valid classes, or a list tuples of valid classes, or a dict where the value is a tuple of value classes

  • path_to_item – (list) the path to the data being validated this stores a list of keys or indices to get to the data being validated

  • spec_property_naming (bool) – True if the variable names in the input data are serialized names as specified in the OpenAPI document. False if the variables names in the input data are python variable names in PEP-8 snake case.

  • _check_type – (boolean) if true, type will be checked and conversion will be attempted.

  • configuration – (Configuration): the configuration class to use when converting file_type items. If passed, conversion will be attempted when possible If not passed, no conversions will be attempted and exceptions will be raised

Returns

the correctly typed value

Raises

ApiTypeError

ncbi.datasets.openapi.model_utils.model_to_dict(model_instance, serialize=True)

Returns the model properties as a dict

Parameters

model_instance (one of your model instances) – the model instance that will be converted to a dict.

Keyword Arguments

serialize (bool) – if True, the keys in the dict will be values from attribute_map

ncbi.datasets.openapi.model_utils.type_error_message(var_value=None, var_name=None, valid_classes=None, key_type=None)
Keyword Arguments
  • var_value (any) – the variable which has the type_error

  • var_name (str) – the name of the variable which has the typ error

  • valid_classes (tuple) – the accepted classes for current_item’s value

  • key_type (bool) – False if our value is a value in a dict True if it is a key in a dict False if our item is an item in a list

ncbi.datasets.openapi.model_utils.get_valid_classes_phrase(input_classes)

Returns a string phrase describing what types are allowed

ncbi.datasets.openapi.model_utils.get_allof_instances(self, model_args, constant_args)
Parameters
  • self – the class we are handling

  • model_args (dict) – var_name to var_value used to make instances

  • constant_args (dict) – metadata arguments: _check_type _path_to_item _spec_property_naming _configuration _visited_composed_classes

Returns

composed_instances (list)

ncbi.datasets.openapi.model_utils.get_oneof_instance(cls, model_kwargs, constant_kwargs, model_arg=None)

Find the oneOf schema that matches the input data (e.g. payload). If exactly one schema matches the input data, an instance of that schema is returned. If zero or more than one schema match the input data, an exception is raised. In OAS 3.x, the payload MUST, by validation, match exactly one of the schemas described by oneOf.

Parameters
  • cls – the class we are handling

  • model_kwargs (dict) – var_name to var_value The input data, e.g. the payload that must match a oneOf schema in the OpenAPI document.

  • constant_kwargs (dict) – var_name to var_value args that every model requires, including configuration, server and path to item.

Kwargs:
model_arg: (int, float, bool, str, date, datetime, ModelSimple, None):

the value to assign to a primitive class or ModelSimple class Notes: - this is only passed in when oneOf includes types which are not object - None is used to suppress handling of model_arg, nullable models are handled in __new__

Returns

oneof_instance (instance)

ncbi.datasets.openapi.model_utils.get_anyof_instances(self, model_args, constant_args)
Parameters
  • self – the class we are handling

  • model_args (dict) – var_name to var_value The input data, e.g. the payload that must match at least one anyOf child schema in the OpenAPI document.

  • constant_args (dict) – var_name to var_value args that every model requires, including configuration, server and path to item.

Returns

anyof_instances (list)

ncbi.datasets.openapi.model_utils.get_discarded_args(self, composed_instances, model_args)

Gathers the args that were discarded by configuration.discard_unknown_keys

ncbi.datasets.openapi.model_utils.validate_get_composed_info(constant_args, model_args, self)

For composed schemas, generate schema instances for all schemas in the oneOf/anyOf/allOf definition. If additional properties are allowed, also assign those properties on all matched schemas that contain additionalProperties. Openapi schemas are python classes.

Exceptions are raised if: - 0 or > 1 oneOf schema matches the model_args input data - no anyOf schema matches the model_args input data - any of the allOf schemas do not match the model_args input data

Parameters
  • constant_args (dict) – these are the args that every model requires

  • model_args (dict) – these are the required and optional spec args that were passed in to make this model

  • self (class) – the class that we are instantiating This class contains self._composed_schemas

Returns

length three
composed_instances (list): the composed instances which are not

self

var_name_to_model_instances (dict): a dict going from var_name

to the model_instance which holds that var_name the model_instance may be self or an instance of one of the classes in self.composed_instances()

additional_properties_model_instances (list): a list of the

model instances which have the property additional_properties_type. This list can include self

Return type

composed_info (list)

Generated October 22, 2021