1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
.. _changes:
Changes in 3.0
==============
This document describes changes to be aware of when switching from 2.x to 3.x.
Backwards-incompatible
----------------------
I tried to keep changes backwards-compatible as much as possible. In some
places, APIs that have changed will trigger a ``DeprecationWarning``.
Database
^^^^^^^^
* ``get_conn()`` has changed to :py:meth:`Database.connection`
* ``get_cursor()`` has changed to :py:meth:`Database.cursor`
* ``execution_context()`` is replaced by simply using the database instance as
a context-manager.
* For a connection context *without* a transaction, use
:py:meth:`Database.connection_context`.
* :py:meth:`Database.create_tables` and :py:meth:`Database.drop_tables`, as
well as :py:meth:`Model.create_table` and :py:meth:`Model.drop_table` all
default to ``safe=True`` (``create_table`` will create if not exists, ``drop_table`` will drop if exists).
* ``connect_kwargs`` attribute has been renamed to ``connect_params``
* initialization parameter for custom field-type definitions has changed
from ``fields`` to ``field_types``.
Model Meta options
^^^^^^^^^^^^^^^^^^
* ``db_table`` has changed to ``table_name``
* ``db_table_func`` has changed to ``table_function``
* ``order_by`` has been removed (used for specifying a default ordering to be
applied to SELECT queries).
* ``validate_backrefs`` has been removed. Back-references are no longer
validated.
Models
^^^^^^
* :py:class:`BaseModel` has been renamed to :py:class:`ModelBase`
* Accessing raw model data is now done using ``__data__`` instead of ``_data``
* The ``_prepare_instance()`` Model method has been removed.
* The ``sqlall()`` method, which output the DDL statements to generate a model
and its associated indexes, has been removed.
Fields
^^^^^^
* ``db_column`` has changed to ``column_name``
* ``db_field`` class attribute changed to ``field_type`` (used if you are
implementing custom field subclasses)
* ``model_class`` attribute has changed to ``model``
* :py:class:`PrimaryKeyField` has been renamed to :py:class:`AutoField`
* :py:class:`ForeignKeyField` constructor has the following changes:
* ``rel_model`` has changed to ``model``
* ``to_field`` has changed to ``field``
* ``related_name`` has changed to ``backref``
* :py:class:`ManyToManyField` is now included in the main ``peewee.py`` module
* Removed the extension fields ``PasswordField``, ``PickledField`` and
``AESEncryptedField``.
Querying
^^^^^^^^
``JOIN_INNER``, ``JOIN_LEFT_OUTER``, etc are now ``JOIN.INNER``,
``JOIN.LEFT_OUTER``, etc.
The C extension that contained implementations of the query result wrappers has
been removed.
Additionally, :py:meth:`Select.aggregate_rows` has been removed. This helper
was used to de-duplicate left-join queries to give the appearance of efficiency
when iterating a model and its relations. In practice, the complexity of the
code and its somewhat limited usefulness convinced me to scrap it. You can
instead use :py:func:`prefetch` to achieve the same result.
* :py:class:`Select` query attribute ``_select`` has changed to ``_returning``
* The ``naive()`` method is now :py:meth:`~BaseQuery.objects`, which defaults
to using the model class as the constructor, but accepts any callable to use
as an alternate constructor.
* The ``annotate()`` query method is no longer supported.
The :py:func:`Case` helper has moved from the ``playhouse.shortcuts`` module
into the main peewee module.
The :py:meth:`~BaseColumn.cast` method is no longer a function, but instead is
a method on all column-like objects.
The ``InsertQuery.return_id_list()`` method has been replaced by a more general
pattern of using :py:meth:`_WriteQuery.returning`.
The ``InsertQuery.upsert()`` method has been replaced by the more general and
flexible :py:meth:`Insert.on_conflict` method.
When using :py:func:`prefetch`, the collected instances will be stored in the
same attribute as the foreign-key's ``backref``. Previously, you would access
joined instances using ``(backref)_prefetch``.
The :py:class:`SQL` object, used to create a composable a SQL string, now
expects the second parameter to be a list/tuple of parameters.
Removed Extensions
^^^^^^^^^^^^^^^^^^
The following extensions are no longer included in the ``playhouse``:
* ``berkeleydb``
* ``csv_utils``
* ``djpeewee``
* ``gfk``
* ``kv``
* ``pskel``
* ``read_slave``
SQLite Extension
^^^^^^^^^^^^^^^^
The SQLite extension module's :py:class:`VirtualModel` class accepts slightly
different ``Meta`` options:
* ``arguments`` - used to specify arbitrary arguments appended after any
columns being defined on the virtual table. Should be a list of strings.
* ``extension_module`` (unchanged)
* ``options`` (replaces ``extension_options``) - arbitrary options for the
virtual table that appear after columns and ``arguments``.
* ``prefix_arguments`` - a list of strings that should appear before any
arguments or columns in the virtual table declaration.
So, when declaring a model for a virtual table, it will be constructed roughly
like this:
.. code-block:: sql
CREATE VIRTUAL TABLE "table name" USING extension_module (
prefix arguments,
field definitions,
arguments,
options)
Postgresql Extension
^^^^^^^^^^^^^^^^^^^^
The `PostgresqlExtDatabase` no longer registers the `hstore` extension by
default. To use the `hstore` extension in 3.0 and onwards, pass
`register_hstore=True` when initializing the database object.
Signals Extension
^^^^^^^^^^^^^^^^^
The ``post_init`` signal has been removed.
New stuff
---------
The query-builder has been rewritten from the ground-up to be more flexible and
powerful. There is now a generic, :ref:`lower-level API <query-builder>` for
constructing queries.
SQLite
^^^^^^
Many SQLite-specific features have been moved from the ``playhouse.sqlite_ext``
module into ``peewee``, such as:
* User-defined functions, aggregates, collations, and table-functions.
* Loading extensions.
* Specifying pragmas.
See the :ref:`"Using SQLite" section <using_sqlite>` and :ref:`"SQLite extensions" <sqlite_ext>`
documents for more details.
SQLite Extension
^^^^^^^^^^^^^^^^
The virtual-table implementation from `sqlite-vtfunc <https://github.com/coleifer/sqlite-vtfunc>`_
has been folded into the peewee codebase.
* Support for SQLite online backup API.
* Murmurhash implementation has been corrected.
* Couple small quirks in the BM25 ranking code have been addressed.
* Numerous user-defined functions for hashing and ranking are now included.
* :py:class:`BloomFilter` implementation.
* Incremental :py:class:`Blob` I/O support.
* Support for update, commit and rollback hooks.
* :py:class:`LSMTable` implementation to support the lsm1 extension.
|
