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
|
.. _transition_to_pydicom1:
Transition to pydicom 1.x
=========================
.. rubric:: Important information on differences in pydicom post 1.0 vs pre-1.0
Introduction
------------
As is often the case for major software version number changes, pydicom 1.0
breaks with the previous release of pydicom (0.9.9) in several ways. These
require changes to user code to target the pydicom >= 1.0 package, or to check
and deal with the differences between the versions.
Backwards-incompatible changes post 1.0
* the library is no longer ``dicom`` but is ``pydicom``, to match the package
name
* short-form names such as ``Beams`` are no longer allowed; use the full
keyword e.g. ``BeamSequence``
* some less-used modules within pydicom have been renamed, e.g. ``dicom.UID``
is now ``pydicom.uid``
Why was the package name changed? There are several reasons for this change:
* it is standard Python practice for the package and the installed library to
have the same name
* first-time users expect to be able to type ``import pydicom`` rather than
``import dicom``, which has caused confusion
* it makes sense for search engines - with the correct name it is much easier
to find relevant questions and example code online
The decision wasn't taken lightly, but with a great deal of discussion on the
GitHub issues list. Having made the leap, the rest of this guide should help
smooth the way...
For authors of packages requiring pydicom < 1.0
-----------------------------------------------
The old pydicom releases have been split off into their own package, called
``dicom``, which is now hosted on PyPI. This allows the old library ``dicom``
to co-exist alongside the new library ``pydicom``.
The main things to do, to ensure your old pydicom code will remain functional,
are:
(a) you should ``pip uninstall pydicom`` and ``pip install dicom`` in your
existing pydicom installs
(b) If you have ``requirements.txt`` files, change the pydicom line from
"pydicom" to "dicom" e.g. ``pydicom==0.9.9`` becomes ``dicom==0.9.9``
(c) Change your instructions to users to ``pip install dicom`` rather than
``pip install pydicom``
Error messages relating to the pydicom transition
-------------------------------------------------
This section is here in the hopes of people getting directed to this page on
searches. If that's you, then welcome! Hopefully the information here can get
things going quickly for you.
For those with pydicom < 1.0 installed, on trying to import pydicom, they will
get an ImportError message::
>>> import pydicom # doctest: +SKIP
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named pydicom
Your choice then is to update to pydicom >=1.0 (see Installing pydicom
section), or to instead use ``import dicom`` and follow the old-style pydicom
syntax.
Conversely, if pydicom >= 1.0 is installed, the error message for ``import
dicom`` will look like::
>>> import dicom # doctest: +SKIP
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named dicom
In this case you likely have installed pydicom >= 1.0, and so the ``dicom`` library
does not exist. You can simply ``import pydicom`` instead, and continue with
the new pydicom, or, if you really need the old pydicom, then you should::
pip install dicom
and you should be good to go.
API Changes in version 1.0
==========================
Apart from the change of the package name, there are some changes in
module names, class names, and behavior that may require some code changes.
Changed module names
--------------------
* module ``UID`` is now ``uid``
Changed function and variable names
-----------------------------------
* in module ``datadict``:
* ``dictionaryVM()`` -> ``dictionary_VM``
* ``dictionaryVR()`` -> ``dictionary_VR``
* ``private_dictionaryVM()`` -> ``private_dictionary_VM``
* ``private_dictionaryVR()`` -> ``private_dictionary_VR``
* in module ``filereader``:
* ``read_file()`` -> ``dcmread()`` (but old name remains for compatibility)
* in module ``filewriter``:
* ``write_file()`` -> ``dcmwrite()`` (but old name remains for compatibility)
* module ``tagtools``:
* ``tag_in_exception()`` has been moved to ``tag`` module
* module ``uid``:
* ``UID.is_valid()`` is now a property
* ``NotCompressedPixelTransferSyntaxes`` -> ``UncompressedPixelTransferSyntaxes``
* ``pydicom_root_UID`` -> ``PYDICOM_ROOT_UID``
Removed functions and names
---------------------------
* support for old names (before DICOM keywords) in module ``datadict`` is
gone (``CleanName()``, ``short_name()``, ``long_name()``,
``all_names_for_tag()``
* ``filereader.not_group2()`` is no longer available
* ``uid.pydicom_UIDs`` has been removed
Changed behavior
----------------
* ``dataset.save_as()``: ``TransferSyntaxUID`` not added automatically to ``dataset.file_meta`` if
missing
|
