The picamera library is (at the time of writing) nearly a year old and has
grown quite rapidly in this time. Occasionally, when adding new functionality
to the library, the API is obvious and natural (e.g.
start_recording() and stop_recording()). At
other times, it’s been less obvious (e.g. unencoded captures) and my initial
attempts have proven to be less than ideal. In such situations I’ve endeavoured
to improve the API without breaking backward compatibility by introducing new
methods or attributes and deprecating the old ones.

This means that, as of release 1.8, there’s quite a lot of deprecated
functionality floating around the library which it would be nice to tidy up,
partly to simplify the library for debugging, and partly to simplify it for new
users. To assuage any fears that I’m imminently going to break backward
compatibility: I intend to leave a gap of at least a year between deprecating
functionality and removing it, hopefully providing ample time for people to
migrate their scripts.

Furthermore, to distinguish any release which is backwards incompatible, I
would increment the major version number in accordance with semantic
versioning. In other words, the first release in which currently deprecated
functionality would be removed would be version 2.0, and as of the release of
1.8 it’s at least a year away. Any future 1.x releases will include all
currently deprecated functions.

Of course, that still means people need a way of determining whether their
scripts use any deprecated functionality in the picamera library. All
deprecated functionality is documented, and the documentation includes pointers
to the intended replacement functionality (see raw_format for
example). However, Python also provides excellent methods for determining
automatically whether any deprecated functionality is being used via the
warnings module.

As of release 1.8, all deprecated functionality will raise
DeprecationWarning when used. By default, the Python interpreter
suppresses these warnings (as they’re only of interest to developers, not
users) but you can easily configure different behaviour.

Despite using deprecated functionality the script runs happily (and silently)
with picamera 1.8. To discover what deprecated functions are being used, we add
a couple of lines to tell the warnings module that we want “default” handling
of DeprecationWarning; “default” handling means that the first time an
attempt is made to raise this warning at a particular location, the warning’s
details will be printed to the console. All future invocations from the same
location will be ignored. This saves flooding the console with warning details
from tight loops. With this change, the script looks like this:

This tells us which pieces of deprecated functionality are being used in our
script, but it doesn’t tell us where in the script they were used. For this,
it is more useful to have warnings converted into full blown exceptions. With
this change, each time a DeprecationWarning would have been printed, it
will instead cause the script to terminate with an unhandled exception and a
full stack trace:

Traceback (most recent call last):
File "test_deprecated.py", line 10, in <module>camera.framerate=(24,1)
File "/usr/share/pyshared/picamera/camera.py", line 1888, in _set_frameraten,d=to_rational(value)
File "/usr/share/pyshared/picamera/camera.py", line 149, in to_rational"Setting framerate or gains as a tuple is deprecated; "DeprecationWarning: Setting framerate or gains as a tuple is deprecated; please use one of Python's many numeric classes like int, float, Decimal, or Fraction instead

This tells us that line 10 of our script is using deprecated functionality, and
provides a hint of how to fix it. We change line 10 to use an int instead of a
tuple for the framerate. Now we run again, and this time get the following:

The script now runs to completion, so we can be confident it’s no longer using
any deprecated functionality and will run happily even when this functionality
is removed in release 2.0. At this point, you may wish to remove the
filterwarnings line as well (or at least comment it out).

For convenience, all currently deprecated functionality is detailed below. You
may wish to skim this list to check whether you’re currently using deprecated
functions, but I would urge users to take advantage of the warnings system
documented in the prior section as well.

In very early versions of picamera, unencoded captures were created by
specifying the 'raw' format with the capture() method, with
the raw_format attribute providing the actual encoding. The
attribute is deprecated, as is usage of the value 'raw' with the format
parameter of all the capture methods.

The deprecated method of taking unencoded captures looks like this:

camera.raw_format='rgb'camera.capture('output.data',format='raw')

In such cases, simply remove references to raw_format and
place the required format directly within the capture() call:

The quantization parameter for start_recording() and
record_sequence() is deprecated in favor of the quality
parameter; this change was made to keep the recording methods consistent with
the capture methods, and to make the meaning of the parameter more obvious to
newcomers. The values of the parameter remain the same (i.e. 1-100 for MJPEG
recordings with higher values indicating higher quality, and 1-40 for H.264
recordings with lower values indicating higher quality).

The deprecated method of setting recording quality looks like this:

camera.start_recording('foo.h264',quantization=25)

Simply replace the quantization parameter with the quality parameter
like so:

Several attributes in picamera expect rational (fractional) values. In early
versions of picamera, these values could only be specified as a tuple expressed
as (numerator,denominator). In later versions, support was expanded to
accept any of Python’s numeric types.

The following code illustrates the deprecated usage of a tuple representing
a rational value:

camera.framerate=(24,1)

Such cases can be replaced with any of Python’s numeric types, including
int, float,
Decimal, and Fraction. All the following
examples are functionally equivalent to the deprecated example above:

These attributes return a Fraction instance as well, but
one modified to permit access as a tuple in order to maintain backward
compatibility. This is also deprecated behaviour. The following example
demonstrates accessing the framerate attribute as a tuple:

n,d=camera.framerateprint('The framerate is %d/%d fps'%(n,d))

In such cases, use the standard numerator and
denominator attributes of the returned fraction
instead:

Release 1.8 introduced rather sweeping changes to the preview system to
incorporate the ability to create multiple static overlays on top of the
preview. As a result, the preview system is no longer incorporated into the
PiCamera class. Instead, it is represented by the
preview attribute which is a separate
PiPreviewRenderer instance when the preview is active.

Unfortuantely, this simple change is not possible when preview attributes are
altered before the preview has been activated, as the
preview attribute is None when the preview is not active.
To accomodate this use-case, optional parameters were added to
start_preview() to provide initial settings for the preview
renderer. The following example illustrates the deprecated method of setting
preview related attribtues prior to activating the preview:

Remove the lines setting the attributes, and use the corresponding keyword
parameters of the start_preview() method instead:

camera.start_preview(alpha=128,fullscreen=False,window=(0,0,640,480))

Finally, the previewing attribute is now obsolete (and thus
deprecated) as its functionality can be trivially obtained by checking the
preview attribute. The following example illustrates the
deprecated method of checking whether the preview is activate:

ifcamera.previewing:print('The camera preview is running')else:print('The camera preview is not running')

In release 1.8, the base PiArrayOutput class was changed to
derive from io.BytesIO in order to add support for seeking, and to
improve performance. The prior implementation had been non-seekable, and
therefore to accommodate re-use of the stream between captures the
truncate() method had an unusual side-effect not
seen with regular Python streams: after truncation, the position of the stream
was set to the new length of the stream. In all other Python streams, the
truncate method doesn’t affect the stream position. The method is
overridden in 1.8 to maintain its unusual behaviour, but this behaviour is
nonetheless deprecated.

The following snippet illustrates the method of truncating an array stream
in picamera versions 1.7 and older:

Unfortunately, this will not work if your script needs to work with prior
versions of picamera as well (since such streams were non-seekable in prior
versions). In this case, call seekable() to determine the
correct course of action:

In release 1.8, the crop attribute was renamed to
zoom; the old name was retained as a deprecated alias for
backward compatibility. This change was made as crop was a thoroughly
misleading name for the attribute (which actually sets the “region of interest”
for the sensor), leading to numerous support questions.

Over time, several capabilities were added to the H.264 encoder in the GPU
firmware. This expanded the number of possible frame types from a simple
key-frame / non-key-frame affair, to a multitude of possibilities (P-frame,
I-frame, SPS/PPS header, motion vector data, and who knows in future). Rather
than keep adding more and more boolean fields to the PiVideoFrame
named tuple, release 1.5 introduced the PiVideoFrameType enumeration
used by the frame_type attribute and deprecated the
keyframe and header attributes.

The following code illustrates usage of the deprecated boolean fields:

In release 1.10, the annotate_background attribute was
enhanced to support setting the background color of annotation text. Older
versions of picamera treated this attribute as a bool (False for no
background, True to draw a black background).

In order to provide the new functionality while maintaining a certain amount of
backward compatibility, the new attribute accepts None for no background
and a Color instance for a custom background color. It is worth
noting that the truth values of None and False are equivalent, as are
the truth values of a Color instance and True. Hence, naive tests
against the attribute value will continue to work.

The following example illustrates the deprecated behaviour of setting the
attribute as a boolean:

camera.annotate_background=Falsecamera.annotate_background=True

In such cases, replace False with None, and True with a
Color instance of your choosing. Bear in mind that older Pi firmwares
can only produce a black background, so you may wish to stick with black to
ensure equivalent behaviour: