The 0.8.0 release of wq.db brings significant improvements over previous versions, and also a number of breaking changes. In particular, wq.db 0.8.0 adds support for Django REST Framework 3.1 and Django 1.8, but drops support for DRF 2.4 and Django 1.6. In addition, a number of APIs have been simplified (or removed!) to make everything easier to use and understand. The implementation is a bit leaner, though the reduction in code is offset by a number of new test cases.
Admittedly, this release breaks more things than previous releases, but the DRF change was significant enough on its own that it made sense to get everything else over with at the same time. If you have an existing project running wq.db 0.7.2 or earlier and would like to upgrade, be sure you are ready to simultaneously upgrade Django and Django REST Framework, as well as make a number of small changes to your use of the model registration API. The upgrade notes below should help you migrate over.
This will be the last major release of wq.db before version 1.0. wq.db 1.0 will likely be very similar to 0.8.0, but with a cleaner separation of the patterns and rest components and a clearer route for defining custom patterns (#35).
The Road to 1.0
- wq.app 0.8 (open issues)
- wq 0.8 (waiting on wq.app 0.8 and wq/wq#9)
- Patterns API Improvements (wq/wq.db#35, wq/wq.app#38)
- wq (.app,.db,.io) 1.0
- Updates to support Django REST Framework 3 and Django 1.8 (#32, #34, #36)
- Improved patterns with support for the HTML JSON forms field naming convention for submitting “child”/”attachment” records together with a parent object (#33). The “classic” form syntax is still supported but will be dropped in wq.db 1.0. To facilitate rendering lists of attachments in edit views, an array
@indexattribute (inspired by Handlebars) has been added to the Mustache template context.
wq.db.rest.context_processors, for better compatibility with wq/app.js (#25).
- Include a serialization of the referenced
content_objectin serializers for attachment models in
- Throw a configuration error if a model is registered with the same name or url as an existing model (#21).
- Ensure that patterns models aren’t added to content types if they aren’t used (#14).
- Significantly increased test coverage.
- Various minor bug fixes.
- The model registration API in
wq.db.rest.apphas been moved to
wq.db.rest. This makes the API even more similar to Django’s
admin, and also eliminates the already overloaded use of “app” as an identifier. As part of this change,
wq.db.rest.settingshas been moved to
wq.db.default_settings. For examples, see item 1 in the upgrade notes below.
patternsconvenience modules (e.g.
wq.db.patterns.admin, and the new
wq.db.patterns.serializers) no longer import everything from the corresponding Django or DRF namespaces. This makes it clearer where various classes are coming from. For examples, see item 2 in upgrade notes below.
- Dropped compatibility with Django 1.6 (#31) and Django REST Framework 2.X. wq.db 0.8.0 and later will not work with these versions. All compatibility hacks for Django 1.6 have been removed, as has support for South, now that migrations are built in to Django 1.7 and higher.
- The default
ModelSerializerclass no longer attempts to automatically create certain one-to-many nested serializers, e.g. the
annotationsattribute on serializers for
AnnotatedModelsubclasses (#22). This “magic” behavior proved to be confusing and hard to override. Instead, models extending
AnnotatedModelor other patterns should be registered with custom serializers, e.g.
AnnotatedModelSerializer. For an example, see Item 2 in the upgrade notes below. Custom nested serializers can be added using the standard Django REST Framework serializer syntax.
- Since it’s now much easier to create custom patterns and nested serializers, the annotate pattern is no longer swappable (see #6) and no longer includes a
- Previous versions of the
ModelSerializerwould serialize foreign keys as
[fieldname]_id, but expect form submissions to use
_idsuffix). Needless to say, this inconsistency was confusing to work with. In wq.db 0.8.0, foreign keys are both sent and recieved with the
_idsuffix (#11). For an example, see item 4 in the upgrade notes below. As before, the
[fieldname]without the suffix can be used in detail templates to retrieve properties from the referenced object.
- The JSONP-based AMD serializer has been removed. This was primarily there to make it possible to load the wq configuration object via
config.js. This file can be generated from the command line via
context variable has been removed in favor of Django's built-in.
If you are starting with a new project, you shouldn’t need to worry about anything in this section. If you have an existing project, you will want to take the following steps:
Update all references to
wq.db.rest.app(e.g. in your
urls.py), and references to
wq.db.rest.settings(e.g. in your
# Old from wq.db.rest import app from .models import MyModel app.router.register_model(MyModel) # New from wq.db import rest from .models import MyModel rest.router.register_model(MyModel)
# Old from wq.db.rest import app app.autodiscover() urlpatterns = patterns('', url(r'^', include(app.router.urls)) ) # New from wq.db import rest rest.autodiscover() urlpatterns = patterns('', url(r'^', include(rest.router.urls)) )
# Old from wq.db.rest.settings import ( TEMPLATE_LOADERS, TEMPLATE_CONTEXT_PROCESSORS, ... # New from wq.db.default_settings import ( TEMPLATE_LOADERS, TEMPLATE_CONTEXT_PROCESSORS, ...
If you are using any of the patterns modules, check all of your
models.pyand be sure you explicitly import
# Old from wq.db.patterns import models class MyModel(models.IdentifiedModel): name = models.CharField(max_length=255) # New from django.db import models from wq.db.patterns import models as patterns class MyModel(patterns.IdentifiedModel): name = models.CharField(max_length=255)
You will also want to update how you register patterns model subclasses with the rest API:
# Old from wq.db.rest import app from .models import MyModel app.router.register_model(MyModel) # New from wq.db import rest from wq.db.patterns import rest as patterns from .models import MyModel rest.router.register_model( MyModel, serializer=patterns.IdentifiedModelSerializer )
- If you are using your own serializer classes, read the Django REST Framework 3.0 release notes and make any necessary changes. In particular, note the new use of
ListSerializerclasses and the renamed
Update your “edit” templates to use
[fieldname]_idwhen referencing foreign keys.
<!-- Old --> <input type="hidden" name="type" value=""> <select name="species"> <option value=""></option> </select> <!-- New --> <input type="hidden" name="type_id" value=""> <select name="species_id"> <option value=""></option> </select>
Also, update your
partials/csrf.htmlto use the new context variable name
<!-- Old --> <input type="hidden" name="csrfmiddlewaretoken" value=""> <!-- New --> <input type="hidden" name="csrfmiddlewaretoken" value="">
If you are using one or more patterns, you may also want to take advantage of the new
<input>naming convention. This will be required as of wq.db 1.0, but both styles are supported for the time being. See the documentation for the individual patterns modules for more information.