wq.db 0.8.0
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
Enhancements
- 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
@index
attribute (inspired by Handlebars) has been added to the Mustache template context. - Added
and
to thewq.db.rest.context_processors
, for better compatibility with wq/app.js (#25). - Include a serialization of the referenced
content_object
in serializers for attachment models inpatterns
(#7). - 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.
Breaking Changes
- The model registration API in
wq.db.rest.app
has been moved towq.db.rest
. This makes the API even more similar to Django’sadmin
, and also eliminates the already overloaded use of “app” as an identifier. As part of this change,wq.db.rest.settings
has been moved towq.db.default_settings
. For examples, see item 1 in the upgrade notes below. - The
patterns
convenience modules (e.g.wq.db.patterns.models
,wq.db.patterns.admin
, and the newwq.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
ModelSerializer
class no longer attempts to automatically create certain one-to-many nested serializers, e.g. theannotations
attribute on serializers forAnnotatedModel
subclasses (#22). This “magic” behavior proved to be confusing and hard to override. Instead, models extendingAnnotatedModel
or 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
contenttype
property onAnnotationType
. - Previous versions of the
ModelSerializer
would serialize foreign keys as[fieldname]_id
, but expect form submissions to use[fieldname]
(without the_id
suffix). 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_id
suffix (#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./manage.py dump_config
. - The
context variable has been removed in favor of Django's built-in
.
Upgrade Notes
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*/rest.py
and yoururls.py
), and references towq.db.rest.settings
(e.g. in yoursettings.py
).*/rest.py
# 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)
urls.py
# 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)) )
settings.py
# 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.py
and be sure you explicitly importdjango.db.models
.# 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
ListSerializer
classes and the renamedto_representation
/to_internal_value
methods. -
Update your “edit” templates to use
[fieldname]_id
when 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.html
to 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.