Overview

audoma.choices

audoma.choices.make_choices(name: str, choices_tuple: Tuple[Any, str, str]) → audoma.choices._T

audoma.decorators

audoma_action.__init__(collectors: Optional[Union[Dict[str, Dict[int, Union[str, Type[rest_framework.serializers.BaseSerializer]]]], Dict[str, Union[str, Type[rest_framework.serializers.BaseSerializer]]], str, Type[rest_framework.serializers.BaseSerializer]]] = None, results: Optional[Union[Dict[str, Dict[int, Union[str, Type[rest_framework.serializers.BaseSerializer]]]], Dict[str, Union[str, Type[rest_framework.serializers.BaseSerializer]]], str, Type[rest_framework.serializers.BaseSerializer]]] = None, errors: Optional[List[Union[Exception, Type[Exception]]]] = None, many: bool = False, ignore_view_collectors: bool = False, run_get_object: Optional[bool] = None, **kwargs) → None
audoma_action.__call__(func: Callable) → Callable

” Call of audoma_action decorator. This is where the magic happens.

Args:

func - decorated function

Returns:

wrapper callable.

class audoma.decorators.AudomaActionException
class audoma.decorators.AudomaArgs(results: Union[Dict[str, Dict[int, Union[str, Type[rest_framework.serializers.BaseSerializer]]]], Dict[str, Union[str, Type[rest_framework.serializers.BaseSerializer]]], str, Type[rest_framework.serializers.BaseSerializer]], collectors: Union[Dict[str, Dict[int, Union[str, Type[rest_framework.serializers.BaseSerializer]]]], Dict[str, Union[str, Type[rest_framework.serializers.BaseSerializer]]], str, Type[rest_framework.serializers.BaseSerializer]], errors: List[Union[Exception, Type[Exception]]], many: bool)

audoma.examples

class audoma.examples.Example(field, example=<class 'audoma.examples.DEFAULT'>)

Class that represents an example for a field. It allows to add example to the field during initialization.

generate_value() → Type[audoma.examples.DEFAULT]
get_value() → Any
to_representation(value) → Any
class audoma.examples.NumericExample(field, example=<class 'audoma.examples.DEFAULT'>)
generate_value() → float

Extracts information from the field and generates a random value based on min_value and max_value.

Returns:

Random value between min_value and max_value

class audoma.examples.RegexExample(field, example=<class 'audoma.examples.DEFAULT'>)
generate_value() → str

Extracts information from the field and generates a random value based on field’s RegexValidators.

Returns:

Generated regex string if regex is found, otherwise returns None

audoma.hooks

audoma.hooks.postprocess_common_errors_section(result: dict, request, **kwargs) → dict

Postprocessing hook which adds COMMON_API_ERRORS description to the API description.

audoma.hooks.preprocess_include_path_format(endpoints: Tuple[str, str, str, Callable], **kwargs) → List[Tuple[str, str, str, Callable]]

Preprocessing hook that filters {format} prefdixed paths, in case schema pattern prefix is used and {format} path params are wanted.

audoma.mixins

class audoma.mixins.Base64ExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)
audoma_example_class

alias of audoma.examples.Base64Example

class audoma.mixins.DateExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)
audoma_example_class

alias of audoma.examples.DateExample

class audoma.mixins.DateTimeExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)
audoma_example_class

alias of audoma.examples.DateTimeExample

class audoma.mixins.ExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)

A mixin class that adds an example to the field in documentation by overriding field parameter in _spectacular_annotation.

Args:
audoma_example_classType[Example]

The class that will be used to create the example. Depends on the type of field

audoma_example_class

alias of audoma.examples.Example

class audoma.mixins.NumericExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)

A mixin class that adds an example to the field in documentation for numeric fields

audoma_example_class

alias of audoma.examples.NumericExample

class audoma.mixins.RangeExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)
audoma_example_class

alias of audoma.examples.RangeExample

class audoma.mixins.RegexExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)

A mixin class that adds an example to the field in documentation for regex fields

audoma_example_class

alias of audoma.examples.RegexExample

class audoma.mixins.TimeExampleMixin(*args, example=<class 'audoma.examples.DEFAULT'>, **kwargs)
audoma_example_class

alias of audoma.examples.TimeExample

audoma.openapi

class audoma.openapi.AudomaAutoSchema
_build_exclusive_fields_schema(schema: dict, exclusive_fields: List[str]) → List[dict]
_extract_action_function(view) → Callable
_extract_audoma_action_operations(view: django.views.generic.base.View, serializer_type: str) → Union[Dict[str, drf_spectacular.utils.OpenApiResponse], Dict[str, rest_framework.serializers.BaseSerializer], Dict[str, Type[rest_framework.serializers.BaseSerializer]], Dict[str, Dict[int, rest_framework.serializers.BaseSerializer]], Dict[int, drf_spectacular.utils.OpenApiResponse]]

Extracts the audoma action operations from the view

_get_enum_choices_for_field(field)
_get_permissions_description() → str
_get_request_for_media_type(serializer)
_get_response_for_code(serializer, status_code, media_types=None)
_get_serializer(serializer_type: str = 'collect') → Union[rest_framework.serializers.BaseSerializer, Type[rest_framework.serializers.BaseSerializer]]
_handle_permission(permission_class: Union[rest_framework.permissions.OperandHolder, rest_framework.permissions.SingleOperandHolder, rest_framework.permissions.BasePermission], operations: list, current_operation: Type = <class 'rest_framework.permissions.AND'>) → dict
_map_serializer(serializer: Union[drf_spectacular.types.OpenApiTypes, rest_framework.serializers.BaseSerializer, Type[rest_framework.serializers.BaseSerializer]], direction: str, bypass_extensions: bool = False) → dict
_map_serializer_field(field: rest_framework.fields.Field, direction: str, bypass_extensions=False) → dict

Allows to use @extend_schema_field with field dict so that it gets updated instead of being overriden

_parse_action_errors(action_errors) → Dict[int, drf_spectacular.utils.OpenApiResponse]
_parse_action_result_serializer(serializer: Union[Type[rest_framework.serializers.BaseSerializer], str], many: bool = False) → Union[rest_framework.serializers.BaseSerializer, str]
_parse_action_result_serializers(action_serializers: Union[Dict[str, Dict[int, Union[str, Type[rest_framework.serializers.BaseSerializer]]]], Dict[str, Union[str, Type[rest_framework.serializers.BaseSerializer]]], str, Type[rest_framework.serializers.BaseSerializer]], many: bool = False) → Union[Dict[str, drf_spectacular.utils.OpenApiResponse], Dict[str, rest_framework.serializers.BaseSerializer], Dict[str, Dict[int, rest_framework.serializers.BaseSerializer]]]
get_description() → str

override this for custom behaviour

get_operation(path, path_regex, path_prefix, method, registry: drf_spectacular.plumbing.ComponentRegistry)
get_operation_id()

override this for custom behaviour

get_response_serializers() → Union[rest_framework.serializers.BaseSerializer, Type[rest_framework.serializers.BaseSerializer]]

overrides this for custom behaviour

audoma.django.db.fields

Audoma Django model Fields This module contains all the fields from Django models with additional functionality. By inheriting from Audoma Mixins, an example is generated for each field (i.e. FloatField will have example generated based on field’s min and max values). We can define custom example by simply passing example as an argument to the field.

class audoma.django.db.fields.AutoField(*args, **kwargs)
class audoma.django.db.fields.BigAutoField(*args, **kwargs)
class audoma.django.db.fields.BigIntegerField(*args, **kwargs)
class audoma.django.db.fields.BinaryField(*args, **kwargs)
class audoma.django.db.fields.BooleanField(*args, **kwargs)
class audoma.django.db.fields.CharField(*args, **kwargs)
class audoma.django.db.fields.CommaSeparatedIntegerField(*args, **kwargs)
class audoma.django.db.fields.CurrencyField(*args, **kwargs)
class audoma.django.db.fields.DateField(*args, **kwargs)
class audoma.django.db.fields.DateTimeField(*args, **kwargs)
class audoma.django.db.fields.DecimalField(*args, **kwargs)
class audoma.django.db.fields.DurationField(*args, **kwargs)
class audoma.django.db.fields.EmailField(*args, **kwargs)
class audoma.django.db.fields.Field(*args, **kwargs)
class audoma.django.db.fields.FilePathField(*args, **kwargs)
class audoma.django.db.fields.FloatField(*args, **kwargs)
class audoma.django.db.fields.GenericIPAddressField(*args, **kwargs)
class audoma.django.db.fields.IPAddressField(*args, **kwargs)
class audoma.django.db.fields.IntegerField(*args, **kwargs)
class audoma.django.db.fields.JSONField(*args, **kwargs)
class audoma.django.db.fields.MACAddressField(*args, **kwargs)
class audoma.django.db.fields.MoneyField(*args, **kwargs)
add_currency_field(cls, name)

Adds CurrencyField instance to a model class and creates example in documentation.

formfield(**kwargs)

Return a django.forms.Field instance for this field.

class audoma.django.db.fields.NullBooleanField(*args, **kwargs)
class audoma.django.db.fields.PhoneNumberField(*args, region=None, **kwargs)
class audoma.django.db.fields.PositiveBigIntegerField(*args, **kwargs)
class audoma.django.db.fields.PositiveIntegerField(*args, **kwargs)
class audoma.django.db.fields.PositiveSmallIntegerField(*args, **kwargs)
class audoma.django.db.fields.SlugField(*args, **kwargs)
class audoma.django.db.fields.SmallAutoField(*args, **kwargs)
class audoma.django.db.fields.SmallIntegerField(*args, **kwargs)
class audoma.django.db.fields.TextField(*args, **kwargs)
class audoma.django.db.fields.TimeField(*args, **kwargs)
class audoma.django.db.fields.URLField(*args, **kwargs)
class audoma.django.db.fields.UUIDField(*args, **kwargs)

audoma.django.forms.fields

class audoma.django.forms.fields.MoneyField(*, max_value=None, min_value=None, max_digits=None, decimal_places=None, **kwargs)
prepare_value(value) → decimal.Decimal

audoma.drf.decorators

audoma.drf.decorators.document_and_format(serializer_or_field: Any) → Callable

audoma.drf.fields

This module is an override for default drf’s field module. Most of those fields, are providing additional example functionality, and also has defined schema type.

class audoma.drf.fields.Base64FileField(*args, **kwargs)
class audoma.drf.fields.Base64ImageField(*args, **kwargs)
class audoma.drf.fields.BooleanField(*args, **kwargs)
class audoma.drf.fields.CharField(*args, **kwargs)
class audoma.drf.fields.ChoiceField(*args, **kwargs)
class audoma.drf.fields.DateField(*args, **kwargs)
class audoma.drf.fields.DateRangeField(*args, **kwargs)
child_class

alias of audoma.drf.fields.DateField

range_type

alias of psycopg2._range.DateRange

class audoma.drf.fields.DateTimeField(*args, **kwargs)
class audoma.drf.fields.DateTimeRangeField(*args, **kwargs)
child_class

alias of audoma.drf.fields.DateTimeField

range_type

alias of psycopg2._range.DateTimeTZRange

class audoma.drf.fields.DecimalField(*args, **kwargs)
class audoma.drf.fields.DecimalRangeField(*args, **kwargs)
child_class

alias of audoma.drf.fields.DecimalField

range_type

alias of psycopg2._range.NumericRange

class audoma.drf.fields.DictField(*args, **kwargs)
class audoma.drf.fields.DurationField(*args, **kwargs)
class audoma.drf.fields.EmailField(*args, **kwargs)
class audoma.drf.fields.FileField(*args, **kwargs)
class audoma.drf.fields.FilePathField(*args, **kwargs)
class audoma.drf.fields.FloatField(*args, **kwargs)
class audoma.drf.fields.FloatRangeField(*args, **kwargs)
child_class

alias of audoma.drf.fields.FloatField

range_type

alias of psycopg2._range.NumericRange

class audoma.drf.fields.HStoreField(*args, **kwargs)
class audoma.drf.fields.IPAddressField(*args, **kwargs)
class audoma.drf.fields.ImageField(*args, **kwargs)
class audoma.drf.fields.IntegerField(*args, **kwargs)
class audoma.drf.fields.IntegerRangeField(*args, **kwargs)
child_class

alias of audoma.drf.fields.IntegerField

range_type

alias of psycopg2._range.NumericRange

class audoma.drf.fields.JSONField(*args, **kwargs)
class audoma.drf.fields.ListField(*args, **kwargs)
class audoma.drf.fields.MACAddressField(*args, **kwargs)
class audoma.drf.fields.MoneyField(*args, **kwargs)
class audoma.drf.fields.MultipleChoiceField(*args, **kwargs)
class audoma.drf.fields.NullBooleanField(*args, **kwargs)
class audoma.drf.fields.PhoneNumberField(*args, **kwargs)
class audoma.drf.fields.RangeField(*args, **kwargs)
class audoma.drf.fields.ReadOnlyField(*args, **kwargs)
class audoma.drf.fields.RegexField(*args, **kwargs)
class audoma.drf.fields.SerializerMethodField(*args, **kwargs)
bind(field_name, parent)

Initializes the field name and parent for the field instance. Called when a field is added to the parent serializer instance.

get_default()

Return the default value to use when validating data if no input is provided for this field.

If a default has not been set for this field then this will simply raise SkipField, indicating that no value should be set in the validated data for this field.

run_validation(data)

Validate a simple representation and return the internal value.

The provided data may be empty if no representation was included in the input.

May raise SkipField if the field should not be included in the validated data.

to_internal_value(data)

Transform the incoming primitive data into a native value.

to_representation(obj)

Transform the outgoing native value into primitive data.

class audoma.drf.fields.SlugField(*args, **kwargs)
class audoma.drf.fields.TimeField(*args, **kwargs)
class audoma.drf.fields.URLField(*args, **kwargs)
class audoma.drf.fields.UUIDField(*args, **kwargs)

audoma.drf.filters

class audoma.drf.filters.DocumentedTypedChoiceFilter(full_choices: NamedTuple, parameter_name: str, **kwargs)

Extended TypedChoiceFilter to generate documentation automatically

audoma.drf.generics

class audoma.drf.generics.GenericAPIView(**kwargs)

Extended GenericAPIView known from rest_framework. This class extends get_serializer and get_serializer_class methods. Also provides get_result_serializer, which is a shourtcut for get_serializer with proper param.

_check_action_function()
_extract_audoma_action_serializer(serializer_type: str, audoma_args: audoma.decorators.AudomaArgs, status_code: Optional[int] = None)
_retrieve_response_headers(status_code: int, result_serializer: rest_framework.serializers.BaseSerializer)
get_audoma_action_config()
get_audoma_action_serializer_class(serializer_type: str, status_code: Optional[int] = None)
get_result_serializer(*args, **kwargs) → rest_framework.serializers.BaseSerializer

Shortuct for get_serializer. Simply has serializer_type set to result

get_serializer(*args, **kwargs) → rest_framework.serializers.BaseSerializer

Passes additional param to get_serializer_class.

kwargs:
serializer_type - defines if serializer is collect or result serializer.

result serializer will be used to produce response, collect to process incoming data.

serializer_class - it is possible to pass serializer_class to get_serializer, this will

ends with returning passed serializer_class object.

Returns:

Object of obtained serializer class.

get_serializer_class(serializer_type: str = 'collect', many: bool = False, status_code: Optional[int] = None, audoma_action_serializer_only: bool = False) → Type[rest_framework.serializers.BaseSerializer]

Extends defuault get_serializer_class method. This returns proper serializer_class for current request.

Args:

serializer_type - serializer_type of serializer to be returned, it may be collect or result serializer.

Returns:

This returns serializer_class

audoma.drf.mixins

This module overwrites basic mixins provided bu django rest framework. Mixins defined here should be used instead of default drf’s mixins. Those mixins should be used to allow usage of extended get_serializer method>

Example:

from audoma.drf import mixins from audoma.drf import viewsets

class ExampleModelViewSet(

mixins.ActionModelMixin, mixins.CreateModelMixin, viewsets.GenericViewSet,

):

serializer_class = ExampleModelSerializer queryset = ExampleModel.objects.all()

class audoma.drf.mixins.ActionModelMixin
get_success_headers(data: dict) → dict
perform_action(request: rest_framework.request.Request, success_status: int = 200, instance: Optional[Any] = None, partial: bool = False, **kwargs) → rest_framework.response.Response
retrieve_instance(request: rest_framework.request.Request, instance: Optional[Any] = None, success_status: int = 200, **kwargs) → rest_framework.response.Response
class audoma.drf.mixins.BulkCreateModelMixin

Either create a single or many model instances in bulk by using the Serializers many=True ability from Django REST >= 2.2.5. .. note:

This mixin uses the same method to create model instances
as ``CreateModelMixin`` because both non-bulk and bulk
requests will use ``POST`` request method.
create(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
perform_bulk_create(serializer: rest_framework.serializers.BaseSerializer) → None
class audoma.drf.mixins.BulkUpdateModelMixin

Update model instances in bulk by using the Serializers many=True ability from Django REST >= 2.2.5.

bulk_update(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
get_object() → Any
partial_bulk_update(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
perform_bulk_update(serializer: rest_framework.serializers.BaseSerializer) → None
perform_update(serializer: rest_framework.serializers.BaseSerializer) → None
class audoma.drf.mixins.CreateModelMixin
create(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
class audoma.drf.mixins.DestroyModelMixin
destroy(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
class audoma.drf.mixins.ListModelMixin
get_paginated_response(data: List[Dict]) → rest_framework.response.Response
list(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
class audoma.drf.mixins.RetrieveModelMixin
retrieve(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response
class audoma.drf.mixins.UpdateModelMixin
update(request: rest_framework.request.Request, *args, **kwargs) → rest_framework.response.Response

audoma.drf.serializers

class audoma.drf.serializers.BulkListSerializer(*args, **kwargs)
class audoma.drf.serializers.DefaultMessageSerializer(*args, **kwargs)
class audoma.drf.serializers.ListSerializer(*args, **kwargs)
class audoma.drf.serializers.ModelSerializer(*args, **kwargs)

Extends default ModelSerializer, modifies serializer_field_mapping (replaces some fields with audoma fields). Adds support for generating audoma example for field.

build_standard_field(field_name, model_field) → Tuple[Union[Type[rest_framework.fields.Field], dict]]

Adds support for mapping example from model fields to model serializer fields.

serializer_choice_field

alias of audoma.drf.fields.ChoiceField

class audoma.drf.serializers.ResultSerializerClassMixin

Allows to define wrap for serializer result.

class audoma.drf.serializers.Serializer(*args, **kwargs)
audoma.drf.serializers.result_serializer_class(SerializerClass: Type[rest_framework.serializers.BaseSerializer]) → Type[rest_framework.serializers.BaseSerializer]

Helper function which wraps the serializer result if necessary.

Args:

  • SerializerClass - serializer class which result should be wrapped

Returns: ResultSerializer class

audoma.drf.validators

class audoma.drf.validators.ExclusiveFieldsValidator(fields: Union[List[str], Tuple[str]], message: Optional[str] = None, required: bool = True, message_required: Optional[str] = None)

This is extra validator defined in audoma. This validator allows to define mutually exclusvie fields.

Attributes:

fields - list or a tuple of mutually exclusive field names message - string validation error message required - boolean value, determines if fields are required message_reqiured - string message if one of fields is required and none has been passed

Args:

fields - list or a tuple of mutually exclusive field names message - string validation error message required - boolean value, determines if fields are required message_reqiured - string message if one of fields is required and none has been passed

message = 'The fields {field_names} are mutually exclusive arguments.'
message_required = 'One of the fields {field_names} is required.'

audoma.drf.viewsets

class audoma.drf.viewsets.AudomaPagination

A simple page number based style that supports page numbers as query parameters.

Note:

If this won’t be used it’ll cause less explicit pagination documentation. This class does not provide any additional functionality.

Args:

page_size (int) - number of items per page - by default this is set to 25 max_page_size (int) - maximum number of items per page - by default this is set to 2000

get_paginated_response_schema(schema: List[dict]) → dict

Simple method to add pagination information to the schema.

Args:

schema (List[dict]) - list of schema items

Returns:

Dictionary with pagination information including examples

max_page_size = 2000
page_size = 25
class audoma.drf.viewsets.GenericViewSet(**kwargs)
_parse_response_data(response_data: Union[List[Any], Dict[Any, Any]]) → Union[List[Any], Dict[Any, Any]]
_parse_single_response_data_item(item)
_simplify_validation_errors(parsed_data)
handle_exception(exc: Exception) → rest_framework.response.Response

Handle any exception that occurs, by returning an appropriate response, or re-raising the error.

pagination_class

alias of audoma.drf.viewsets.AudomaPagination

exception audoma.drf.viewsets.UnknownExceptionContentTypeError