c21130eed9
* module docstrings * db schema graph * dev docs first pass * dev docs pass 2 * add generated notification to top of generated docs files * linting * regen docs Co-authored-by: Stefan Pratter <stefan@20c.com> Co-authored-by: Sunshine Buchholz <sunshine@20c.com>
16 KiB
Generated from serializers.py on 2021-10-15 07:56:57.376975
peeringdb_server.serializers
REST API Serializer definitions. REST API POST / PUT data validators.
New serializers should extend ModelSerializer class, which is a custom extension of django-rest-framework's ModelSerializer.
Custom ModelSerializer implements logic for the expansion of relationships driven by the depth url parameter. The depth parameter indicates how many objects to recurse into.
Special api filtering implementation should be done through the prepare_query
method.
Functions
nested
def nested(serializer, exclude=[], getter=None, through=None, **kwargs)
Use this function to create nested serializer fields. Making depth work otherwise while fetching related lists via handlref remains a mystery.
queryable_field_xl
def queryable_field_xl(fld)
Translate _id into and also translate fac and net queries into "facility" and "network" queries.
FIXME: should be renamed on model schema.
Classes
AddressSerializer
AddressSerializer(rest_framework.serializers.ModelSerializer)
A ModelSerializer is just a regular Serializer, except that:
- A set of default fields are automatically populated.
- A set of default validators are automatically populated.
- Default
.create()and.update()implementations are provided.
The process of automatically determining a set of serializer fields based on the model fields is reasonably complex, but you almost certainly don't need to dig into the implementation.
If the ModelSerializer class doesn't generate the set of fields that
you need you should either declare the extra/differing fields explicitly on
the serializer class, or simply use a Serializer class.
AsnRdapValidator
AsnRdapValidator(builtins.object)
A validator that queries rdap entries for the provided value (Asn) and will fail if no matching asn is found.
Methods
_call_
def __call__(self, attrs)
Call self as a function.
_init_
def __init__(self, field=asn, message=None, methods=None)
Initialize self. See help(type(self)) for accurate signature.
FacilitySerializer
FacilitySerializer(peeringdb_server.serializers.SpatialSearchMixin, peeringdb_server.serializers.GeocodeSerializerMixin, peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.Facility
Possible relationship queries:
- net_id, handled by prepare_query
- ix_id, handled by prepare_query
- org_id, handled by serializer
- org_name, hndled by prepare_query
Methods
to_internal_value
def to_internal_value(self, data)
Dict of native values <- Dict of primitive datatypes.
to_representation
def to_representation(self, instance)
Object instance -> Dict of primitive datatypes.
FieldMethodValidator
FieldMethodValidator(builtins.object)
A validator that will only allow a field to be set for certain methods.
Methods
_call_
def __call__(self, attrs)
Call self as a function.
_init_
def __init__(self, field, methods, message=None)
Initialize self. See help(type(self)) for accurate signature.
GeocodeSerializerMixin
GeocodeSerializerMixin(builtins.object)
Override create() and update() method of serializer to normalize the location against the Google Maps Geocode API and resave the model instance with normalized address fields.
Can only be used if the model includes the GeocodeBaseMixin.
Methods
_add_meta_information
def _add_meta_information(self, metadata)
Adds a dictionary of metadata to the "meta" field of the API request, so that it ends up in the API response.
_geosync_information_present
def _geosync_information_present(self, instance, validated_data)
Determine if there is enough address information to necessitate a geosync attempt.
_need_geosync
def _need_geosync(self, instance, validated_data)
Determine if any geofields that have changed need normalization. Returns False if the only change is that fields have been deleted.
handle_geo_error
def handle_geo_error(self, exc, instance)
Issue #939: In the event that there is an error in geovalidating the address (including address not found), a warning is returned in the "meta" field of the response and null the latitude and longitude on the instance.
needs_address_suggestion
def needs_address_suggestion(self, suggested_address, instance)
Issue #940: If the geovalidated address meaningfully differs from the address the user provided, we return True to signal a address suggestion should be provided to the user.
update
def update(self, instance, validated_data)
When updating a geo-enabled object, update the model first and then normalize the geofields.
IXLanPrefixSerializer
IXLanPrefixSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.IXLanPrefix
Possible relationship queries:
- ixlan_id, handled by serializer
- ix_id, handled by prepare_query
IXLanSerializer
IXLanSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.IXLan
Possible relationship queries:
- ix_id, handled by serializer
InternetExchangeFacilitySerializer
InternetExchangeFacilitySerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.InternetExchangeFacility
Possible relationship queries:
- fac_id, handled by serializer
- ix_id, handled by serializer
InternetExchangeSerializer
InternetExchangeSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.InternetExchange
Possible relationship queries:
- org_id, handled by serializer
- fac_id, handled by prepare_query
- net_id, handled by prepare_query
- ixfac_id, handled by prepare_query
- ixlan_id, handled by prepare_query
Methods
create
def create(self, validated_data)
Entities created via the API should go into the verification queue with status pending if they are in the QUEUE_ENABLED list.
to_representation
def to_representation(self, data)
Object instance -> Dict of primitive datatypes.
ModelSerializer
ModelSerializer(rest_framework.serializers.ModelSerializer)
ModelSerializer that provides DB API with custom params.
Main problem with doing field ops here is data is already fetched, so while it's fine for single columns, it doesn't help on speed for fk relationships. However data is not yet serialized so there may be some gain.
Using custom method fields to introspect doesn't work at all, because they're not called until they're serialized, and then are called once per row,
for example test_depth = serializers.SerializerMethodField('check_for_fk') def check_for_fk(self, obj): print "check ", type(obj)
class Meta: fields = [ 'test_depth', ...
Best bet so far looks like overloading the single object GET in the model view set, and adding on the relationships, but need to GET to GET the fields defined yet not included in the query, may have to rewrite the base class, which would mean talking to the dev and committing back or we'll have this problem every update.
After testing, the time is all in serialization and transfer, so culling related here should be fine.
arg[0] is a queryset, but seems to have already been evaluated
Addition Query arguments:
fields comma separated list of only fields to display
could cull the default list down quite a bit by default and make people ask explicitly for them
self.Meta.default_fields, but I'm not sure it matters, more testing
Instanced Attributes
These attributes / properties will be available on instances of the class
- current_depth (
@property): None - depth (
@property): None - in_list (
@property): None - is_root (
@property): None
Class Methods
default_depth
def default_depth(cls, is_list)
Return default depth according to whether resultset is list or single GET.
depth_from_request
def depth_from_request(cls, request, is_list)
Derive aproporiate depth parameter from request. Max and default depth will vary depending on whether result set is a list or single object.
This will return the depth specified in the request or the next best possible depth.
is_unique_query
def is_unique_query(cls, request)
Check if the request parameters are expected to return a unique entity.
max_depth
def max_depth(cls, is_list)
Return max depth according to whether resultset is list or single GET.
prefetch_related
def prefetch_related(cls, qset, request, prefetch=None, related=None, nested=, depth=None, is_list=False, single=None)
Prefetch related sets according to depth specified in the request.
Prefetched set data will be located off the instances in an attribute called "_set_active_prefetched" where tag is the handleref tag of the objects the set will be holding.
queryable_relations
def queryable_relations(self)
Returns a list of all second level queryable relation fields.
Methods
_init_
def __init__(self, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
create
def create(self, validated_data)
Entities created via the API should go into the verification queue with status pending if they are in the QUEUE_ENABLED list.
finalize_create
def finalize_create(self, request)
This will be called on the end of POST request to this serializer.
finalize_delete
def finalize_delete(self, request)
This will be called on the end of DELETE request to this serializer.
finalize_update
def finalize_update(self, request)
This will be called on the end of PUT request to this serializer.
run_validation
def run_validation(self, data=<class 'rest_framework.fields.empty'>)
Custom validation handling.
Will run the vanilla django-rest-framework validation but wrap it with logic to handle unique constraint errors to restore soft-deleted objects that are blocking a save on basis of a unique constraint violation.
save
def save(self, **kwargs)
Entities created via API that have status pending should attempt to store which user created the item in the verification queue instance.
to_representation
def to_representation(self, data)
Object instance -> Dict of primitive datatypes.
NetworkContactSerializer
NetworkContactSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.NetworkContact
Possible relationship queries:
- net_id, handled by serializer
Methods
to_representation
def to_representation(self, data)
Object instance -> Dict of primitive datatypes.
NetworkFacilitySerializer
NetworkFacilitySerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.NetworkFacility
Possible relationship queries:
- fac_id, handled by serializer
- net_id, handled by seralizers
Methods
run_validation
def run_validation(self, data=<class 'rest_framework.fields.empty'>)
Custom validation handling.
Will run the vanilla django-rest-framework validation but wrap it with logic to handle unique constraint errors to restore soft-deleted objects that are blocking a save on basis of a unique constraint violation.
NetworkIXLanSerializer
NetworkIXLanSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.NetworkIXLan
Possible relationship queries:
- net_id, handled by serializer
- ixlan_id, handled by serializer
- ix_id, handled by prepare_query
Class Methods
prepare_query
def prepare_query(cls, qset, **kwargs)
Allows filtering by indirect relationships.
Currently supports: ix_id
Methods
_validate_network_contact
def _validate_network_contact(self, data)
Per github ticket #826, a Netixlan is only allowed to be added if there is a network contact that the AC can contact to resolve issues.
run_validation
def run_validation(self, data=<class 'rest_framework.fields.empty'>)
Custom validation handling.
Will run the vanilla django-rest-framework validation but wrap it with logic to handle unique constraint errors to restore soft-deleted objects that are blocking a save on basis of a unique constraint violation.
NetworkSerializer
NetworkSerializer(peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.Network
Possible realtionship queries:
- org_id, handled by serializer
- ix_id, handled by prepare_query
- ixlan_id, handled by prepare_query
- netfac_id, handled by prepare_query
- fac_id, handled by prepare_query
Class Methods
prepare_query
def prepare_query(cls, qset, **kwargs)
Allows filtering by indirect relationships.
Currently supports: ixlan_id, ix_id, netixlan_id, netfac_id, fac_id
Methods
create
def create(self, validated_data)
Entities created via the API should go into the verification queue with status pending if they are in the QUEUE_ENABLED list.
finalize_create
def finalize_create(self, request)
This will be called on the end of POST request to this serializer.
to_internal_value
def to_internal_value(self, data)
Dict of native values <- Dict of primitive datatypes.
OrganizationSerializer
OrganizationSerializer(peeringdb_server.serializers.SpatialSearchMixin, peeringdb_server.serializers.GeocodeSerializerMixin, peeringdb_server.serializers.ModelSerializer)
Serializer for peeringdb_server.models.Organization
Class Methods
prepare_query
def prepare_query(cls, qset, **kwargs)
Add special filter options
Currently supports:
- asn: filter by network asn
ParentStatusException
ParentStatusException(builtins.OSError)
Throw this when an object cannot be created because its parent is either status pending or deleted.
Methods
_init_
def __init__(self, parent, typ)
Initialize self. See help(type(self)) for accurate signature.
RequestAwareListSerializer
RequestAwareListSerializer(rest_framework.serializers.ListSerializer)
A List serializer that has access to the originating request.
Used as the list serializer class for all nested lists so time filters can be applied to the resultset if the _ctf param is set in the request.
Instanced Attributes
These attributes / properties will be available on instances of the class
- request (
@property): Retrieve the request from the root serializer.
Methods
to_representation
def to_representation(self, data)
List of object instances -> List of dicts of primitive datatypes.
RequiredForMethodValidator
RequiredForMethodValidator(builtins.object)
A validator that makes a field required for certain methods.
Methods
_call_
def __call__(self, attrs)
Call self as a function.
_init_
def __init__(self, field, methods=['POST', 'PUT'], message=None)
Initialize self. See help(type(self)) for accurate signature.
SaneIntegerField
SaneIntegerField(rest_framework.fields.IntegerField)
Integer field that renders null values to 0.
Methods
get_attribute
def get_attribute(self, instance)
Given the outgoing object instance, return the primitive value that should be used for this field.
SoftRequiredValidator
SoftRequiredValidator(builtins.object)
A validator that allows us to require that at least one of the specified fields is set.
Methods
_call_
def __call__(self, attrs)
Call self as a function.
_init_
def __init__(self, fields, message=None)
Initialize self. See help(type(self)) for accurate signature.
SpatialSearchMixin
SpatialSearchMixin(builtins.object)
Mixin that enables spatial search for a model with address fields.
At minimum, a model needs a country and city field, but address1, address2, zipcode and state are also considered if they exist.
UniqueFieldValidator
UniqueFieldValidator(builtins.object)
For issue #70:
Django-side unique field validation.
Ideally this is done in mysql, however the other duplicates need to be cleared first, so validate on the django side initially.
Methods
_call_
def __call__(self, attrs)
Call self as a function.
_init_
def __init__(self, fields, message=None, check_deleted=False)
Initialize self. See help(type(self)) for accurate signature.