mirror/peeringdb-peeringdb
1
0
Fork 0
mirror of https://github.com/peeringdb/peeringdb.git synced 2024-05-11 05:55:09 +00:00
Code Releases Activity
Files
master
peeringdb-peeringdb/docs/dev/modules/serializers.py.md
Stefan Pratter 4b10b8e41d Support 202304 (#1383) 
* Don't allow the first and last addresses being assigned #1241

Show all e-mail addresses associated with a username #1291

Add permission 'manage peering sessions' #1290

Put an Icon next to user name on https://www.peeringdb.com/org/nnnn#users if the user is using U2F #1238

Tie TOTP devices and Webauthn Security Keys to the user account #1339

v2 Search (#1204)

pin django peeringdb 3.0.1 and poetry relock

linting

* fix codeql warning: DOM text reinterpreted as HTML

* fix global stats tests

---------

Co-authored-by: 20C <code@20c.com>
2023-05-16 18:04:05 +00:00

810 lines
18 KiB
Markdown
Raw Permalink Blame History

Generated from serializers.py on 2023-04-12 10:09:44.563425
# 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 <fld>_id into <fld> and also translate fac and net queries into "facility"
and "network" queries.
FIXME: should be renamed on model schema.
---
# Classes
---
## ASSetSerializer
```
ASSetSerializer(peeringdb_server.serializers.NetworkSerializer)
```
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
## 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.
---
## CampusSerializer
```
CampusSerializer(peeringdb_server.serializers.SpatialSearchMixin, peeringdb_server.serializers.ModelSerializer)
```
Serializer for peeringdb_server.models.Campus
### Class Methods
#### prepare_query
`def prepare_query(cls, qset, **kwargs)`
Allows filtering by indirect relationships.
Currently supports: facility
---
## CarrierFacilitySerializer
```
CarrierFacilitySerializer(peeringdb_server.serializers.ModelSerializer)
```
Serializer for peeringdb_server.models.CarrierFacility
## CarrierSerializer
```
CarrierSerializer(peeringdb_server.serializers.ModelSerializer)
```
Serializer for peeringdb_server.models.Carrier
### Methods
#### to_representation
`def to_representation(self, data)`
Object instance -> Dict of primitive datatypes.
---
## 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.
### Class Methods
#### normalize_state_lookup
`def normalize_state_lookup(cls, filters)`
for non-distance search the specifies state and country
attempt to normalize the state field using melissa global address
lookup. (#1079)
this does NOT need to be done on distance search since distance search
already normalizes the search to geo-coordinates using melissa.
---
### 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, selective=None)`
Prefetch related sets according to depth specified in the request.
Prefetched set data will be located off the instances in an attribute
called "<tag>_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.
---
#### _handle_netixlan_reclaim
`def _handle_netixlan_reclaim(self, ipaddr4, ipaddr6)`
Handles logic of reclaiming ipaddresses from soft-deleted
netixlans in case where ipv4 and ipv6 are on separate netixlan objects
Will raise a django DoesNotExist error if either ipaddress does not
exist on a deleted netixlan
---
#### _render_social_media
`def _render_social_media(self, output)`
Until v3 the `website` field still drives the website url of the object
but we can start rendering in the `social_media` field as well.
---
#### create
`def create(self, validated_data, auto_approve=False)`
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
---
## 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.
---
## SocialMediaSerializer
```
SocialMediaSerializer(rest_framework.serializers.Serializer)
```
Renders the social_media property
## 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.
View Git Blame Copy Permalink