Context Navigation

deprecation.rst

Visit:

Revision 9538, 27.2 kB (checked in by olly, 14 months ago)
docs/deprecation.rst: Move "Stem::stem_word(word)" in the bindings to the right section (it was done in 1.0.0, as already indicated). Deprecate the non-pythonic iterators in favour of the pythonic ones.

Line
1	.. This document was originally written by Richard Boulton.
2
3	.. Copyright (C) 2007 Lemur Consulting Ltd
4	.. Copyright (C) 2007 Olly Betts
5
6	===========
7	Deprecation
8	===========
9
10	.. contents:: Table of contents
11
12	Introduction
13	============
14
15	Xapian's API is fairly stable and has been polished piece by piece over time,
16	but it still occasionally needs to be changed. This may be because a new
17	feature has been implemented and the interface needs to allow access to it, but
18	it may also be required in order to polish a rough edge which has been missed
19	in earlier versions of Xapian, or simply to reflect an internal change which
20	requires a modification to the external interface.
21
22	We aim to make such changes in a way that allows developers to work against a
23	stable API, while avoiding the need for the Xapian developers to maintain too
24	many old historical interface artifacts. This document describes the process
25	we use to deprecate old pieces of the API, lists parts of the API which are
26	currently marked as deprecated, and also describes parts of the API which have
27	been deprecated for some time, and are now removed from the Xapian library.
28
29	It is possible for functions, methods, constants, types or even whole classes
30	to be deprecated, but to save words this document will often use the term
31	"features" to refer collectively to any of these types of interface items.
32
33
34	Deprecation Procedure
35	=====================
36
37	Deprecation markers
38	-------------------
39
40	At any particular point, some parts of the C++ API will be marked as
41	"deprecated". This is indicated with the ``XAPIAN_DEPRECATED`` macro, which
42	will cause compilers with appropriate support (such as GCC 3.1 or later, and
43	MSVC 7.0 or later) to emit warning messages about the use of deprecated
44	features at compile time.
45
46	If a feature is marked with one of these markers, you should avoid using it in
47	new code, and should migrate your code to use a replacement when possible. The
48	documentation comments for the feature, or the list at the end
49	of this file, will describe possible alternatives to the deprecated feature.
50
51	API and ABI compatibility
52	-------------------------
53
54	Within a series of releases with a given major and minor number, we try to
55	maintain API and ABI forwards compatibility. This means that an application
56	written and compiled against version `X.Y.a` of Xapian should work, without any
57	changes or need to recompile, with a later version `X.Y.b`, for all `a` <= `b`.
58
59	It is possible that a feature may be marked as deprecated within a minor
60	release series - that is from version `X.Y.c`
61	onwards, where `c` is not zero. The API and ABI will not be changed by this
62	deprecation, since the feature will still be available in the API (though the
63	change may cause the compiler to emit new warnings at compile time).
64
65	In general, a feature will be supported after being deprecated for an entire
66	series of releases with a given major and minor number. For example, if a
67	feature is deprecated in release `1.2.0`, it will be supported for the entire
68	`1.2.x` release series, and removed in release `1.3.0`. If a feature is
69	deprecated in release `1.2.5`, it will be supported for all remaining releases
70	in the `1.2.x` series, and also for all releases in the `1.3.x` series, and
71	will be removed in release `1.4.0`.
72
73	However, this rule may not be followed in all cases. In particular, if a
74	feature was marked as "temporary" in the documentation, it may be removed
75	faster (and possibly, without even passing through a stage of being
76	deprecated).
77
78	Deprecation in the bindings
79	---------------------------
80
81	When the Xapian API changes, the interface provided by the Xapian bindings will
82	usually change in step. In addition, it is sometimes necessary to change the
83	way in which Xapian is wrapped by bindings - for example, to provide a better
84	convenience wrapper for iterators in Python. Again, we aim to ensure that an
85	application written (and compiled, if the language being bound is a compiled
86	language) for version `X.Y.a` of Xapian should work without any changes or need
87	to recompile, with a later version `X.Y.b`, for all `a` <= `b`.
88
89	However, the bindings are a little less mature than the core C++ API, so we
90	don't intend to give the same guarantee that a feature present and not
91	deprecated in version `X.Y.a` will work in all versions `X+1.Y.b`. In other
92	words, we may remove features which have been deprecated without waiting for
93	an entire release series to pass.
94
95	Any planned deprecations will be documented in the list of deprecations and
96	removed features at the end of this file.
97
98
99	How to avoid using deprecated features
100	======================================
101
102	We recommend taking the following steps to avoid depending on deprecated
103	features when writing your applications:
104
105	- If at all possible, test compile your project using a compiler which
106	supports warnings about deprecated features (such as GCC 3.1 or later), and
107	check for such warnings. Use the -Werror flag to GCC to ensure that you
108	don't miss any of them.
109
110	- Check the NEWS file for each new release for details of any new features
111	which are deprecated in the release.
112
113	- Check the documentation comments, or the automatically extracted API
114	documentation, for each feature you use in your application. This
115	documentation will indicate features which are deprecated, or planned for
116	deprecation.
117
118	- For applications which are not written in C++, there is currently no
119	equivalent of the ``XAPIAN_DEPRECATED`` macro for the bindings, and thus
120	there is no way for the bindings to give a warning if a deprecated feature
121	is used. This would be a nice addition for those languages in which there
122	is a reasonable way to give such warnings. Until such a feature is
123	implemented, all application writers using the bindings can do is to check
124	the list of deprecated features in each new release, or lookup the features
125	they are using in the list at the end of this file.
126
127
128	Features currently marked for deprecation
129	=========================================
130
131	Native C++ API
132	--------------
133
134	.. Keep table width to <= 126 columns.
135
136	========== ====== =================================== ========================================================================
137	Deprecated Remove Feature name Upgrade suggestion and comments
138	========== ====== =================================== ========================================================================
139	0.9.6 1.1.0 xapian_version_string() Use ``version_string()`` instead.
140	---------- ------ ----------------------------------- ------------------------------------------------------------------------
141	0.9.6 1.1.0 xapian_major_version() Use ``major_version()`` instead.
142	---------- ------ ----------------------------------- ------------------------------------------------------------------------
143	0.9.6 1.1.0 xapian_minor_version() Use ``minor_version()`` instead.
144	---------- ------ ----------------------------------- ------------------------------------------------------------------------
145	0.9.6 1.1.0 xapian_revision() Use ``revision()`` instead.
146	---------- ------ ----------------------------------- ------------------------------------------------------------------------
147	1.0.0 1.1.0 Enquire::include_query_terms Use ``Enquire::INCLUDE_QUERY_TERMS`` instead.
148	---------- ------ ----------------------------------- ------------------------------------------------------------------------
149	1.0.0 1.1.0 Enquire::use_exact_termfreq Use ``Enquire::USE_EXACT_TERMFREQ`` instead.
150	---------- ------ ----------------------------------- ------------------------------------------------------------------------
151	1.0.0 1.1.0 Error::get_errno() Use ``Error::get_error_string()`` instead.
152	---------- ------ ----------------------------------- ------------------------------------------------------------------------
153	1.0.0 1.1.0 The Quartz backend Use the Flint backend instead.
154	---------- ------ ----------------------------------- ------------------------------------------------------------------------
155	1.0.0 1.1.0 Quartz::open() Use ``Flint::open()`` instead.
156	---------- ------ ----------------------------------- ------------------------------------------------------------------------
157	1.0.0 1.1.0 quartzcheck Use ``xapian-check`` instead.
158	---------- ------ ----------------------------------- ------------------------------------------------------------------------
159	1.0.0 1.1.0 quartzcompact Use ``xapian-compact`` instead.
160	---------- ------ ----------------------------------- ------------------------------------------------------------------------
161	1.0.3 1.1.0 Enquire::register_match_decider() This method didn't do anything, so just remove calls to it!
162	---------- ------ ----------------------------------- ------------------------------------------------------------------------
163	1.0.3 1.2.0? ``Database::positionlist_begin()`` This check is quite expensive, and often you don't care. If you
164	throwing ``RangeError`` if the do it's easy to check - just open a ``TermListIterator`` for the
165	term specified doesn't index the document and use ``skip_to()`` to check if the term is there.
166	document specified.
167	---------- ------ ----------------------------------- ------------------------------------------------------------------------
168	1.0.3 1.2.0? ``Database::positionlist_begin()`` This check is quite expensive, and often you don't care. If you
169	throwing ``DocNotFoundError`` if do, it's easy to check - just call ``Database::get_document()`` with the
170	the document specified doesn't specified document ID.
171	exist.
172	---------- ------ ----------------------------------- ------------------------------------------------------------------------
173	1.0.4 1.1.0 Query::Query(Query::op, Query) This constructor isn't useful for any currently implemented
174	``Query::op``.
175	========== ====== =================================== ========================================================================
176
177
178	Bindings
179	--------
180
181	.. Keep table width to <= 126 columns.
182
183	========== ====== ======== ============================ ======================================================================
184	Deprecated Remove Language Feature name Upgrade suggestion and comments
185	========== ====== ======== ============================ ======================================================================
186	0.9.6 1.1.0 SWIG xapian_version_string() Use ``version_string()`` instead.
187	[#swig]_
188	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
189	0.9.6 1.1.0 SWIG xapian_major_version() Use ``major_version()`` instead.
190	[#swig]_
191	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
192	0.9.6 1.1.0 SWIG xapian_minor_version() Use ``minor_version()`` instead.
193	[#swig]_
194	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
195	0.9.6 1.1.0 SWIG xapian_revision() Use ``revision()`` instead.
196	[#swig]_
197	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
198	1.0.0 1.1.0 SWIG ESet::get_termname() Use ``ESet::get_term()`` instead. This change is intended to bring
199	[#swig]_ the ESet iterators in line with other term iterators, which all
200	support ``get_term()`` instead of ``get_termname()``.
201	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
202	1.0.0 1.1.0 Python get_description() All ``get_description()`` methods have been renamed to ``__str__()``,
203	so the normal python ``str()`` function can be used.
204	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
205	1.0.0 1.1.0 Python MSetItem.get_*() All these methods are deprecated, in favour of properties.
206	To convert, just change ``msetitem.get_FOO()`` to ``msetitem.FOO``
207	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
208	1.0.0 1.1.0 Python Enquire.get_matching_terms Replaced by ``Enquire.matching_terms``, for consistency with
209	rest of Python API.
210	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
211	1.0.0 1.1.0 SWIG Error::get_errno() Use ``Error::get_error_string()`` instead.
212	[#swig]_
213	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
214	0.9.6 1.1.0 SWIG MSet::get_document_id() Use ``MSet::get_docid()`` instead.
215	[#swg2]_
216	---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
217	1.0.4 1.2.0 Python Non-pythonic iterators Use the pythonic iterators instead.
218	========== ====== ======== ============================ ======================================================================
219
220	.. [#swig] This affects all SWIG-generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp)
221
222	.. [#swg2] This affects all SWIG-generated bindings except those for Ruby, support for which was added after the function waan-core.
223
224	Omega
225	-----
226
227	.. Keep table width to <= 126 columns.
228
229	========== ====== =================================== ========================================================================
230	Deprecated Remove Feature name Upgrade suggestion and comments
231	========== ====== =================================== ========================================================================
232	0.9.5 1.1.0 scriptindex index=nopos Use ``indexnopos`` instead.
233	========== ====== =================================== ========================================================================
234
235	Features removed from Xapian
236	============================
237
238	Native C++ API
239	--------------
240
241	.. Keep table width to <= 126 columns.
242
243	======= =================================== ==================================================================================
244	Removed Feature name Upgrade suggestion and comments
245	======= =================================== ==================================================================================
246	1.0.0 QueryParser::set_stemming_options() Use ``set_stemmer()``, ``set_stemming_strategy()`` and/or ``set_stopper()``
247	instead:
248
249	- ``set_stemming_options("")`` becomes
250	``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)``
251
252	- ``set_stemming_options("none")`` becomes
253	``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)``
254
255	- ``set_stemming_options(LANG)`` becomes
256	``set_stemmer(Xapian::Stem(LANG)`` and
257	``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)``
258
259	- ``set_stemming_options(LANG, false)`` becomes
260	``set_stemmer(Xapian::Stem(LANG)`` and
261	``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)``
262
263	- ``set_stemming_options(LANG, true)`` becomes
264	``set_stemmer(Xapian::Stem(LANG)`` and
265	``set_stemming_strategy(Xapian::QueryParser::STEM_ALL)``
266
267	If a third parameter is passed, ``set_stopper(PARAM3)`` and treat the first two
268	parameters as above.
269	------- ----------------------------------- ----------------------------------------------------------------------------------
270	1.0.0 Enquire::set_sort_forward() Use ``Enquire::set_docid_order()`` instead:
271
272	- ``set_sort_forward(true)`` becomes ``set_docid_order(ASCENDING)``
273	- ``set_sort_forward(false)`` becomes ``set_docid_order(DESCENDING)``
274	------- ----------------------------------- ----------------------------------------------------------------------------------
275	1.0.0 Enquire::set_sorting() Use ``Enquire::set_sort_by_relevance()``, ``Enquire::set_sort_by_value()``, or
276	``Enquire::set_sort_by_value_then_relevance()`` instead.
277
278	- ``set_sorting(KEY, 1)`` becomes ``set_sort_by_value(KEY)``
279	- ``set_sorting(KEY, 1, false)`` becomes ``set_sort_by_value(KEY)``
280	- ``set_sorting(KEY, 1, true)`` becomes ``set_sort_by_value_then_relevance(KEY)``
281	- ``set_sorting(ANYTHING, 0)`` becomes ``set_sort_by_relevance()``
282	- ``set_sorting(Xapian::BAD_VALUENO, ANYTHING)`` becomes
283	``set_sort_by_relevance()``
284	------- ----------------------------------- ----------------------------------------------------------------------------------
285	1.0.0 Stem::stem_word(word) Use ``Stem::operator()(word)`` instead.
286	------- ----------------------------------- ----------------------------------------------------------------------------------
287	1.0.0 Auto::open(path) Use the ``Database(path)`` constructor instead.
288	------- ----------------------------------- ----------------------------------------------------------------------------------
289	1.0.0 Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead.
290	------- ----------------------------------- ----------------------------------------------------------------------------------
291	1.0.0 Query::is_empty() Use ``Query::empty()`` instead.
292	------- ----------------------------------- ----------------------------------------------------------------------------------
293	1.0.0 Document::add_term_nopos() Use ``Document::add_term()`` instead.
294	------- ----------------------------------- ----------------------------------------------------------------------------------
295	1.0.0 Enquire::set_bias() No replacement yet implemented.
296	------- ----------------------------------- ----------------------------------------------------------------------------------
297	1.0.0 ExpandDecider::operator() Return type is now ``bool`` not ``int``.
298	------- ----------------------------------- ----------------------------------------------------------------------------------
299	1.0.0 MatchDecider::operator() Return type is now ``bool`` not ``int``.
300	------- ----------------------------------- ----------------------------------------------------------------------------------
301	1.0.0 Error::get_type() Return type is now ``const char *`` not ``std::string``. Most existing code
302	won't need changes, but if it does the simplest fix is to write
303	``std::string(e.get_type())`` instead of ``e.get_type()``.
304	------- ----------------------------------- ----------------------------------------------------------------------------------
305	1.0.0 <xapian/output.h> Use ``cout << obj.get_description();`` instead of ``cout << obj;``
306	------- ----------------------------------- ----------------------------------------------------------------------------------
307	1.0.0 Several constructors marked Explicitly create the object type required, for example use
308	as explicit. ``Xapian::Enquire enq(Xapian::Database(path));`` instead of
309	``Xapian::Enquire enq(path);``
310	------- ----------------------------------- ----------------------------------------------------------------------------------
311	1.0.0 QueryParser::parse_query() throwing Catch ``Xapian::QueryParserError`` instead of ``const char *``, and call
312	``const char *`` exception. ``get_msg()`` on the caught object. If you need to build with either version,
313	catch both (you'll need to compile the part which catches ``QueryParserError``
314	conditionally, since this exception isn't present in the 0.9 release series).
315	======= =================================== ==================================================================================
316
317
318	Bindings
319	--------
320
321	.. Keep table width to <= 126 columns.
322
323	======= ======== ============================ ================================================================================
324	Removed Language Feature name Upgrade suggestion and comments
325	======= ======== ============================ ================================================================================
326	1.0.0 SWIG Enquire::set_sort_forward() Use ``Enquire::set_docid_order()`` instead.
327	[#rswg]_
328	- ``set_sort_forward(true)`` becomes ``set_docid_order(ASCENDING)``
329	- ``set_sort_forward(false)`` becomes ``set_docid_order(DESCENDING)``
330	------- -------- ---------------------------- --------------------------------------------------------------------------------
331	1.0.0 SWIG Enquire::set_sorting() Use ``Enquire::set_sort_by_relevance()``, ``Enquire::set_sort_by_value()``
332	[#rswg]_ or ``Enquire::set_sort_by_value_then_relevance()`` instead.
333
334	- ``set_sorting(KEY, 1)`` becomes ``set_sort_by_value(KEY)``
335	- ``set_sorting(KEY, 1, false) becomes ``set_sort_by_value(KEY)``
336	- ``set_sorting(KEY, 1, true)`` becomes
337	``set_sort_by_value_then_relevance(KEY)``
338	- ``set_sorting(ANYTHING, 0) becomes set_sort_by_relevance()``
339	- ``set_sorting(Xapian::BAD_VALUENO, ANYTHING)`` becomes
340	``set_sort_by_relevance()``
341	------- -------- ---------------------------- --------------------------------------------------------------------------------
342	1.0.0 SWIG Auto::open(path) Use the ``Database(path)`` constructor instead.
343	[#rswg]_
344
345	------- -------- ---------------------------- --------------------------------------------------------------------------------
346	1.0.0 SWIG Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead.
347	[#rswg]_
348	------- -------- ---------------------------- --------------------------------------------------------------------------------
349	1.0.0 SWIG MSet::is_empty() Use ``MSet::empty()`` instead.
350	[#rsw3]_
351	------- -------- ---------------------------- --------------------------------------------------------------------------------
352	1.0.0 SWIG ESet::is_empty() Use ``ESet::empty()`` instead.
353	[#rsw3]_
354	------- -------- ---------------------------- --------------------------------------------------------------------------------
355	1.0.0 SWIG RSet::is_empty() Use ``RSet::empty()`` instead.
356	[#rsw3]_
357	------- -------- ---------------------------- --------------------------------------------------------------------------------
358	1.0.0 SWIG Query::is_empty() Use ``Query::empty()`` instead.
359	[#rsw3]_
360	------- -------- ---------------------------- --------------------------------------------------------------------------------
361	1.0.0 SWIG Document::add_term_nopos() Use ``Document::add_term()`` instead.
362	[#rswg]_
363	------- -------- ---------------------------- --------------------------------------------------------------------------------
364	1.0.0 CSharp ExpandDecider::Apply() Return type is now ``bool`` instead of ``int``.
365	------- -------- ---------------------------- --------------------------------------------------------------------------------
366	1.0.0 CSharp MatchDecider::Apply() Return type is now ``bool`` instead of ``int``.
367	------- -------- ---------------------------- --------------------------------------------------------------------------------
368	1.0.0 SWIG Stem::stem_word(word) Use ``Stem::operator()(word)`` instead. [#callable]_
369	[#rswg]_
370	======= ======== ============================ ================================================================================
371
372	.. [#rswg] This affects all SWIG generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp)
373
374	.. [#rsw3] This affects all SWIG generated bindings except those for Ruby, which was added after the function was deprecated in Xapian-core, and PHP, where empty is a reserved word (and therefore, the method remains "is_empty").
375
376	.. [#callable] Python handles this like C++. Ruby renames it to 'call' (idiomatic Ruby). PHP renames it to 'apply'. CSharp to 'Apply' (delegates could probably be used to provide C++-like functor syntax, but that's effort and it seems debatable if it would actually be more natural to a C# programmer). Tcl8 renames it to 'apply' - need to ask a Tcl type if that's the best solution.
377
378	Omega
379	-----
380
381	.. Keep table width to <= 126 columns.
382
383	======= =================================== ==================================================================================
384	Removed Feature name Upgrade suggestion and comments
385	======= =================================== ==================================================================================
386	1.0.0 $freqs Use ``$map{$queryterms,$_: $nice{$freq{$_}}}`` instead.
387	------- ----------------------------------- ----------------------------------------------------------------------------------
388	1.0.0 scriptindex -u ``-u`` was ignored for compatibility with 0.7.5 and earlier, so just remove it.
389	------- ----------------------------------- ----------------------------------------------------------------------------------
390	1.0.0 scriptindex -q ``-q`` was ignored for compatibility with 0.6.1 and earlier, so just remove it.
391	======= =================================== ==================================================================================

Note: See TracBrowser for help on using the browser.

Context Navigation

root / tags / 1.0.8 / xapian-core / docs / deprecation.rst

Download in other formats: