Source code

Download source archive ↓

src/openpyxl/chart/axis.py

1# Copyright (c) 2010-2024 openpyxl
2
3from openpyxl.descriptors.serialisable import Serialisable
4from openpyxl.descriptors import (
5    Typed,
6    Float,
7    NoneSet,
8    Bool,
9    Integer,
10    MinMax,
11    NoneSet,
12    Set,
13    String,
14    Alias,
15)
16
17from openpyxl.descriptors.excel import (
18    ExtensionList,
19    Percentage,
20    _explicit_none,
21)
22from openpyxl.descriptors.nested import (
23    NestedValue,
24    NestedSet,
25    NestedBool,
26    NestedNoneSet,
27    NestedFloat,
28    NestedInteger,
29    NestedMinMax,
30)
31from openpyxl.xml.constants import CHART_NS
32
33from .descriptors import NumberFormatDescriptor
34from .layout import Layout
35from .text import Text, RichText
36from .shapes import GraphicalProperties
37from .title import Title, TitleDescriptor
38
39
40class ChartLines(Serialisable):
41
42    tagname = "chartLines"
43
44    spPr = Typed(expected_type=GraphicalProperties, allow_none=True)
45    graphicalProperties = Alias('spPr')
46
47    def __init__(self, spPr=None):
48        self.spPr = spPr
49
50
51class Scaling(Serialisable):
52
53    tagname = "scaling"
54
55    logBase = NestedFloat(allow_none=True)
56    orientation = NestedSet(values=(['maxMin', 'minMax']))
57    max = NestedFloat(allow_none=True)
58    min = NestedFloat(allow_none=True)
59    extLst = Typed(expected_type=ExtensionList, allow_none=True)
60
61    __elements__ = ('logBase', 'orientation', 'max', 'min',)
62
63    def __init__(self,
64                 logBase=None,
65                 orientation="minMax",
66                 max=None,
67                 min=None,
68                 extLst=None,
69                ):
70        self.logBase = logBase
71        self.orientation = orientation
72        self.max = max
73        self.min = min
74
75
76class _BaseAxis(Serialisable):
77
78    axId = NestedInteger(expected_type=int)
79    scaling = Typed(expected_type=Scaling)
80    delete = NestedBool(allow_none=True)
81    axPos = NestedSet(values=(['b', 'l', 'r', 't']))
82    majorGridlines = Typed(expected_type=ChartLines, allow_none=True)
83    minorGridlines = Typed(expected_type=ChartLines, allow_none=True)
84    title = TitleDescriptor()
85    numFmt = NumberFormatDescriptor()
86    number_format = Alias("numFmt")
87    majorTickMark = NestedNoneSet(values=(['cross', 'in', 'out']), to_tree=_explicit_none)
88    minorTickMark = NestedNoneSet(values=(['cross', 'in', 'out']), to_tree=_explicit_none)
89    tickLblPos = NestedNoneSet(values=(['high', 'low', 'nextTo']))
90    spPr = Typed(expected_type=GraphicalProperties, allow_none=True)
91    graphicalProperties = Alias('spPr')
92    txPr = Typed(expected_type=RichText, allow_none=True)
93    textProperties = Alias('txPr')
94    crossAx = NestedInteger(expected_type=int) # references other axis
95    crosses = NestedNoneSet(values=(['autoZero', 'max', 'min']))
96    crossesAt = NestedFloat(allow_none=True)
97
98    # crosses & crossesAt are mutually exclusive
99
100    __elements__ = ('axId', 'scaling', 'delete', 'axPos', 'majorGridlines',
101                    'minorGridlines', 'title', 'numFmt', 'majorTickMark', 'minorTickMark',
102                    'tickLblPos', 'spPr', 'txPr', 'crossAx', 'crosses', 'crossesAt')
103
104    def __init__(self,
105                 axId=None,
106                 scaling=None,
107                 delete=None,
108                 axPos='l',
109                 majorGridlines=None,
110                 minorGridlines=None,
111                 title=None,
112                 numFmt=None,
113                 majorTickMark=None,
114                 minorTickMark=None,
115                 tickLblPos=None,
116                 spPr=None,
117                 txPr= None,
118                 crossAx=None,
119                 crosses=None,
120                 crossesAt=None,
121                ):
122        self.axId = axId
123        if scaling is None:
124            scaling = Scaling()
125        self.scaling = scaling
126        self.delete = delete
127        self.axPos = axPos
128        self.majorGridlines = majorGridlines
129        self.minorGridlines = minorGridlines
130        self.title = title
131        self.numFmt = numFmt
132        self.majorTickMark = majorTickMark
133        self.minorTickMark = minorTickMark
134        self.tickLblPos = tickLblPos
135        self.spPr = spPr
136        self.txPr = txPr
137        self.crossAx = crossAx
138        self.crosses = crosses
139        self.crossesAt = crossesAt
140
141
142class DisplayUnitsLabel(Serialisable):
143
144    tagname = "dispUnitsLbl"
145
146    layout = Typed(expected_type=Layout, allow_none=True)
147    tx = Typed(expected_type=Text, allow_none=True)
148    text = Alias("tx")
149    spPr = Typed(expected_type=GraphicalProperties, allow_none=True)
150    graphicalProperties = Alias("spPr")
151    txPr = Typed(expected_type=RichText, allow_none=True)
152    textPropertes = Alias("txPr")
153
154    __elements__ = ('layout', 'tx', 'spPr', 'txPr')
155
156    def __init__(self,
157                 layout=None,
158                 tx=None,
159                 spPr=None,
160                 txPr=None,
161                ):
162        self.layout = layout
163        self.tx = tx
164        self.spPr = spPr
165        self.txPr = txPr
166
167
168class DisplayUnitsLabelList(Serialisable):
169
170    tagname = "dispUnits"
171
172    custUnit = NestedFloat(allow_none=True)
173    builtInUnit = NestedNoneSet(values=(['hundreds', 'thousands',
174                                         'tenThousands', 'hundredThousands', 'millions', 'tenMillions',
175                                         'hundredMillions', 'billions', 'trillions']))
176    dispUnitsLbl = Typed(expected_type=DisplayUnitsLabel, allow_none=True)
177    extLst = Typed(expected_type=ExtensionList, allow_none=True)
178
179    __elements__ = ('custUnit', 'builtInUnit', 'dispUnitsLbl',)
180
181    def __init__(self,
182                 custUnit=None,
183                 builtInUnit=None,
184                 dispUnitsLbl=None,
185                 extLst=None,
186                ):
187        self.custUnit = custUnit
188        self.builtInUnit = builtInUnit
189        self.dispUnitsLbl = dispUnitsLbl
190
191
192class NumericAxis(_BaseAxis):
193
194    tagname = "valAx"
195
196    axId = _BaseAxis.axId
197    scaling = _BaseAxis.scaling
198    delete = _BaseAxis.delete
199    axPos = _BaseAxis.axPos
200    majorGridlines = _BaseAxis.majorGridlines
201    minorGridlines = _BaseAxis.minorGridlines
202    title = _BaseAxis.title
203    numFmt = _BaseAxis.numFmt
204    majorTickMark = _BaseAxis.majorTickMark
205    minorTickMark = _BaseAxis.minorTickMark
206    tickLblPos = _BaseAxis.tickLblPos
207    spPr = _BaseAxis.spPr
208    txPr = _BaseAxis.txPr
209    crossAx = _BaseAxis.crossAx
210    crosses = _BaseAxis.crosses
211    crossesAt = _BaseAxis.crossesAt
212
213    crossBetween = NestedNoneSet(values=(['between', 'midCat']))
214    majorUnit = NestedFloat(allow_none=True)
215    minorUnit = NestedFloat(allow_none=True)
216    dispUnits = Typed(expected_type=DisplayUnitsLabelList, allow_none=True)
217    extLst = Typed(expected_type=ExtensionList, allow_none=True)
218
219    __elements__ = _BaseAxis.__elements__ + ('crossBetween', 'majorUnit',
220                                             'minorUnit', 'dispUnits',)
221
222
223    def __init__(self,
224                 crossBetween=None,
225                 majorUnit=None,
226                 minorUnit=None,
227                 dispUnits=None,
228                 extLst=None,
229                 **kw
230                ):
231        self.crossBetween = crossBetween
232        self.majorUnit = majorUnit
233        self.minorUnit = minorUnit
234        self.dispUnits = dispUnits
235        kw.setdefault('majorGridlines', ChartLines())
236        kw.setdefault('axId', 100)
237        kw.setdefault('crossAx', 10)
238        super().__init__(**kw)
239
240
241    @classmethod
242    def from_tree(cls, node):
243        """
244        Special case value axes with no gridlines
245        """
246        self = super().from_tree(node)
247        gridlines = node.find("{%s}majorGridlines" % CHART_NS)
248        if gridlines is None:
249            self.majorGridlines = None
250        return self
251
252
253
254class TextAxis(_BaseAxis):
255
256    tagname = "catAx"
257
258    axId = _BaseAxis.axId
259    scaling = _BaseAxis.scaling
260    delete = _BaseAxis.delete
261    axPos = _BaseAxis.axPos
262    majorGridlines = _BaseAxis.majorGridlines
263    minorGridlines = _BaseAxis.minorGridlines
264    title = _BaseAxis.title
265    numFmt = _BaseAxis.numFmt
266    majorTickMark = _BaseAxis.majorTickMark
267    minorTickMark = _BaseAxis.minorTickMark
268    tickLblPos = _BaseAxis.tickLblPos
269    spPr = _BaseAxis.spPr
270    txPr = _BaseAxis.txPr
271    crossAx = _BaseAxis.crossAx
272    crosses = _BaseAxis.crosses
273    crossesAt = _BaseAxis.crossesAt
274
275    auto = NestedBool(allow_none=True)
276    lblAlgn = NestedNoneSet(values=(['ctr', 'l', 'r']))
277    lblOffset = NestedMinMax(min=0, max=1000)
278    tickLblSkip = NestedInteger(allow_none=True)
279    tickMarkSkip = NestedInteger(allow_none=True)
280    noMultiLvlLbl = NestedBool(allow_none=True)
281    extLst = Typed(expected_type=ExtensionList, allow_none=True)
282
283    __elements__ = _BaseAxis.__elements__ + ('auto', 'lblAlgn', 'lblOffset',
284                                             'tickLblSkip', 'tickMarkSkip', 'noMultiLvlLbl')
285
286    def __init__(self,
287                 auto=None,
288                 lblAlgn=None,
289                 lblOffset=100,
290                 tickLblSkip=None,
291                 tickMarkSkip=None,
292                 noMultiLvlLbl=None,
293                 extLst=None,
294                 **kw
295                ):
296        self.auto = auto
297        self.lblAlgn = lblAlgn
298        self.lblOffset = lblOffset
299        self.tickLblSkip = tickLblSkip
300        self.tickMarkSkip = tickMarkSkip
301        self.noMultiLvlLbl = noMultiLvlLbl
302        kw.setdefault('axId', 10)
303        kw.setdefault('crossAx', 100)
304        super().__init__(**kw)
305
306
307class DateAxis(TextAxis):
308
309    tagname = "dateAx"
310
311    axId = _BaseAxis.axId
312    scaling = _BaseAxis.scaling
313    delete = _BaseAxis.delete
314    axPos = _BaseAxis.axPos
315    majorGridlines = _BaseAxis.majorGridlines
316    minorGridlines = _BaseAxis.minorGridlines
317    title = _BaseAxis.title
318    numFmt = _BaseAxis.numFmt
319    majorTickMark = _BaseAxis.majorTickMark
320    minorTickMark = _BaseAxis.minorTickMark
321    tickLblPos = _BaseAxis.tickLblPos
322    spPr = _BaseAxis.spPr
323    txPr = _BaseAxis.txPr
324    crossAx = _BaseAxis.crossAx
325    crosses = _BaseAxis.crosses
326    crossesAt = _BaseAxis.crossesAt
327
328    auto = NestedBool(allow_none=True)
329    lblOffset = NestedInteger(allow_none=True)
330    baseTimeUnit = NestedNoneSet(values=(['days', 'months', 'years']))
331    majorUnit = NestedFloat(allow_none=True)
332    majorTimeUnit = NestedNoneSet(values=(['days', 'months', 'years']))
333    minorUnit = NestedFloat(allow_none=True)
334    minorTimeUnit = NestedNoneSet(values=(['days', 'months', 'years']))
335    extLst = Typed(expected_type=ExtensionList, allow_none=True)
336
337    __elements__ = _BaseAxis.__elements__ + ('auto', 'lblOffset',
338                                             'baseTimeUnit', 'majorUnit', 'majorTimeUnit', 'minorUnit',
339                                             'minorTimeUnit')
340
341    def __init__(self,
342                 auto=None,
343                 lblOffset=None,
344                 baseTimeUnit=None,
345                 majorUnit=None,
346                 majorTimeUnit=None,
347                 minorUnit=None,
348                 minorTimeUnit=None,
349                 extLst=None,
350                 **kw
351                ):
352        self.auto = auto
353        self.lblOffset = lblOffset
354        self.baseTimeUnit = baseTimeUnit
355        self.majorUnit = majorUnit
356        self.majorTimeUnit = majorTimeUnit
357        self.minorUnit = minorUnit
358        self.minorTimeUnit = minorTimeUnit
359        kw.setdefault('axId', 500)
360        kw.setdefault('lblOffset', lblOffset)
361        super().__init__(**kw)
362
363
364class SeriesAxis(_BaseAxis):
365
366    tagname = "serAx"
367
368    axId = _BaseAxis.axId
369    scaling = _BaseAxis.scaling
370    delete = _BaseAxis.delete
371    axPos = _BaseAxis.axPos
372    majorGridlines = _BaseAxis.majorGridlines
373    minorGridlines = _BaseAxis.minorGridlines
374    title = _BaseAxis.title
375    numFmt = _BaseAxis.numFmt
376    majorTickMark = _BaseAxis.majorTickMark
377    minorTickMark = _BaseAxis.minorTickMark
378    tickLblPos = _BaseAxis.tickLblPos
379    spPr = _BaseAxis.spPr
380    txPr = _BaseAxis.txPr
381    crossAx = _BaseAxis.crossAx
382    crosses = _BaseAxis.crosses
383    crossesAt = _BaseAxis.crossesAt
384
385    tickLblSkip = NestedInteger(allow_none=True)
386    tickMarkSkip = NestedInteger(allow_none=True)
387    extLst = Typed(expected_type=ExtensionList, allow_none=True)
388
389    __elements__ = _BaseAxis.__elements__ + ('tickLblSkip', 'tickMarkSkip')
390
391    def __init__(self,
392                 tickLblSkip=None,
393                 tickMarkSkip=None,
394                 extLst=None,
395                 **kw
396                ):
397        self.tickLblSkip = tickLblSkip
398        self.tickMarkSkip = tickMarkSkip
399        kw.setdefault('axId', 1000)
400        kw.setdefault('crossAx', 10)
401        super().__init__(**kw)