Debian Codegraph @

src/tinycss/css21.py

raw
1 # coding: utf8
2 """
3 tinycss.css21
4 -------------
5
6 Parser for CSS 2.1
7 http://www.w3.org/TR/CSS21/syndata.html
8
9 :copyright: (c) 2012 by Simon Sapin.
10 :license: BSD, see LICENSE for more details.
11 """
12
13
14 from itertools import chain, islice
15
16 from tinycss.decoding import decode
17 from tinycss.parsing import ParseError, remove_whitespace, split_on_comma, strip_whitespace, validate_any, validate_value
18 from tinycss.token_data import TokenList
19 from tinycss.tokenizer import tokenize_grouped
20
21 # stylesheet : [ CDO | CDC | S | statement ]*;
22 # statement : ruleset | at-rule;
23 # at-rule : ATKEYWORD S* any* [ block | ';' S* ];
24 # block : '{' S* [ any | block | ATKEYWORD S* | ';' S* ]* '}' S*;
25 # ruleset : selector? '{' S* declaration? [ ';' S* declaration? ]* '}' S*;
26 # selector : any+;
27 # declaration : property S* ':' S* value;
28 # property : IDENT;
29 # value : [ any | block | ATKEYWORD S* ]+;
30 # any : [ IDENT | NUMBER | PERCENTAGE | DIMENSION | STRING
31 # | DELIM | URI | HASH | UNICODE-RANGE | INCLUDES
32 # | DASHMATCH | ':' | FUNCTION S* [any|unused]* ')'
33 # | '(' S* [any|unused]* ')' | '[' S* [any|unused]* ']'
34 # ] S*;
35 # unused : block | ATKEYWORD S* | ';' S* | CDO S* | CDC S*;
36
37
38 class Stylesheet:
39 """
40 A parsed CSS stylesheet.
41
42 .. attribute:: rules
43
44 A mixed list, in source order, of :class:`RuleSet` and various
45 at-rules such as :class:`ImportRule`, :class:`MediaRule`
46 and :class:`PageRule`.
47 Use their :obj:`at_keyword` attribute to distinguish them.
48
49 .. attribute:: errors
50
51 A list of :class:`~.parsing.ParseError`. Invalid rules and declarations
52 are ignored, with the details logged in this list.
53
54 .. attribute:: encoding
55
56 The character encoding that was used to decode the stylesheet
57 from bytes, or ``None`` for Unicode stylesheets.
58
59 """
60 def __init__(self, rules, errors, encoding):
61 self.rules = rules
62 self.errors = errors
63 self.encoding = encoding
64
65 def __repr__(self):
66 return '<{0.__class__.__name__} {1} rules {2} errors>'.format(
67 self, len(self.rules), len(self.errors))
68
69
70 class AtRule:
71 """
72 An unparsed at-rule.
73
74 .. attribute:: at_keyword
75
76 The normalized (lower-case) at-keyword as a string. Eg: ``'@page'``
77
78 .. attribute:: head
79
80 The part of the at-rule between the at-keyword and the ``{``
81 marking the body, or the ``;`` marking the end of an at-rule without
82 a body. A :class:`~.token_data.TokenList`.
83
84 .. attribute:: body
85
86 The content of the body between ``{`` and ``}`` as a
87 :class:`~.token_data.TokenList`, or ``None`` if there is no body
88 (ie. if the rule ends with ``;``).
89
90 The head was validated against the core grammar but **not** the body,
91 as the body might contain declarations. In case of an error in a
92 declaration, parsing should continue from the next declaration.
93 The whole rule should not be ignored as it would be for an error
94 in the head.
95
96 These at-rules are expected to be parsed further before reaching
97 the user API.
98
99 """
100
101 __slots__ = 'at_keyword', 'head', 'body', 'line', 'column'
102
103 def __init__(self, at_keyword, head, body, line, column):
104 self.at_keyword = at_keyword
105 self.head = TokenList(head)
106 self.body = TokenList(body) if body is not None else body
107 self.line = line
108 self.column = column
109
110 def __repr__(self):
111 return ('<{0.__class__.__name__} {0.line}:{0.column} {0.at_keyword}>'
112 .format(self))
113
114
115 class RuleSet:
116 """A ruleset.
117
118 .. attribute:: at_keyword
119
120 Always ``None``. Helps to tell rulesets apart from at-rules.
121
122 .. attribute:: selector
123
124 The selector as a :class:`~.token_data.TokenList`.
125 In CSS 3, this is actually called a selector group.
126
127 ``rule.selector.as_css()`` gives the selector as a string.
128 This string can be used with *cssselect*, see :ref:`selectors3`.
129
130 .. attribute:: declarations
131
132 The list of :class:`Declaration`, in source order.
133
134 """
135
136 at_keyword = None
137 __slots__ = 'selector', 'declarations', 'line', 'column'
138
139 def __init__(self, selector, declarations, line, column):
140 self.selector = TokenList(selector)
141 self.declarations = declarations
142 self.line = line
143 self.column = column
144
145 def __repr__(self):
146 return ('<{0.__class__.__name__} at {0.line}:{0.column} {1}>'
147 .format(self, self.selector.as_css()))
148
149
150 class Declaration:
151 """A property declaration.
152
153 .. attribute:: name
154
155 The property name as a normalized (lower-case) string.
156
157 .. attribute:: value
158
159 The property value as a :class:`~.token_data.TokenList`.
160
161 The value is not parsed. UAs using tinycss may only support
162 some properties or some values and tinycss does not know which.
163 They need to parse values themselves and ignore declarations with
164 unknown or unsupported properties or values, and fall back
165 on any previous declaration.
166
167 :mod:`tinycss.color3` parses color values, but other values
168 will need specific parsing/validation code.
169
170 .. attribute:: priority
171
172 Either the string ``'important'`` or ``None``.
173
174 """
175 __slots__ = 'name', 'value', 'priority', 'line', 'column'
176
177 def __init__(self, name, value, priority, line, column):
178 self.name = name
179 self.value = TokenList(value)
180 self.priority = priority
181 self.line = line
182 self.column = column
183
184 def __repr__(self):
185 priority = ' !' + self.priority if self.priority else ''
186 return ('<{0.__class__.__name__} {0.line}:{0.column}'
187 ' {0.name}: {1}{2}>'.format(
188 self, self.value.as_css(), priority))
189
190
191 class PageRule:
192 """A parsed CSS 2.1 @page rule.
193
194 .. attribute:: at_keyword
195
196 Always ``'@page'``
197
198 .. attribute:: selector
199
200 The page selector.
201 In CSS 2.1 this is either ``None`` (no selector), or the string
202 ``'first'``, ``'left'`` or ``'right'`` for the pseudo class
203 of the same name.
204
205 .. attribute:: specificity
206
207 Specificity of the page selector. This is a tuple of four integers,
208 but these tuples are mostly meant to be compared to each other.
209
210 .. attribute:: declarations
211
212 A list of :class:`Declaration`, in source order.
213
214 .. attribute:: at_rules
215
216 The list of parsed at-rules inside the @page block, in source order.
217 Always empty for CSS 2.1.
218
219 """
220 at_keyword = '@page'
221 __slots__ = 'selector', 'specificity', 'declarations', 'at_rules', 'line', 'column'
222
223 def __init__(self, selector, specificity, declarations, at_rules,
224 line, column):
225 self.selector = selector
226 self.specificity = specificity
227 self.declarations = declarations
228 self.at_rules = at_rules
229 self.line = line
230 self.column = column
231
232 def __repr__(self):
233 return ('<{0.__class__.__name__} {0.line}:{0.column}'
234 ' {0.selector}>'.format(self))
235
236
237 class MediaRule:
238 """A parsed @media rule.
239
240 .. attribute:: at_keyword
241
242 Always ``'@media'``
243
244 .. attribute:: media
245
246 For CSS 2.1 without media queries: the media types
247 as a list of strings.
248
249 .. attribute:: rules
250
251 The list :class:`RuleSet` and various at-rules inside the @media
252 block, in source order.
253
254 """
255 at_keyword = '@media'
256 __slots__ = 'media', 'rules', 'line', 'column'
257
258 def __init__(self, media, rules, line, column):
259 self.media = media
260 self.rules = rules
261 self.line = line
262 self.column = column
263
264 def __repr__(self):
265 return ('<{0.__class__.__name__} {0.line}:{0.column}'
266 ' {0.media}>'.format(self))
267
268
269 class ImportRule:
270 """A parsed @import rule.
271
272 .. attribute:: at_keyword
273
274 Always ``'@import'``
275
276 .. attribute:: uri
277
278 The URI to be imported, as read from the stylesheet.
279 (URIs are not made absolute.)
280
281 .. attribute:: media
282
283 For CSS 2.1 without media queries: the media types
284 as a list of strings.
285 This attribute is explicitly ``['all']`` if the media was omitted
286 in the source.
287
288 """
289 at_keyword = '@import'
290 __slots__ = 'uri', 'media', 'line', 'column'
291
292 def __init__(self, uri, media, line, column):
293 self.uri = uri
294 self.media = media
295 self.line = line
296 self.column = column
297
298 def __repr__(self):
299 return ('<{0.__class__.__name__} {0.line}:{0.column}'
300 ' {0.uri}>'.format(self))
301
302
303 def _remove_at_charset(tokens):
304 """Remove any valid @charset at the beginning of a token stream.
305
306 :param tokens:
307 An iterable of tokens
308 :returns:
309 A possibly truncated iterable of tokens
310
311 """
312 tokens = iter(tokens)
313 header = list(islice(tokens, 4))
314 if [t.type for t in header] == ['ATKEYWORD', 'S', 'STRING', ';']:
315 atkw, space, string, semicolon = header
316 if ((atkw.value, space.value) == ('@charset', ' ')
317 and string.as_css()[0] == '"'):
318 # Found a valid @charset rule, only keep what’s after it.
319 return tokens
320 return chain(header, tokens)
321
322
323 class CSS21Parser:
324 """Parser for CSS 2.1
325
326 This parser supports the core CSS syntax as well as @import, @media,
327 @page and !important.
328
329 Note that property values are still not parsed, as UAs using this
330 parser may only support some properties or some values.
331
332 Currently the parser holds no state. It being a class only allows
333 subclassing and overriding its methods.
334
335 """
336
337 def __init__(self):
338 self.at_parsers = {
339 '@' + x:getattr(self, 'parse_%s_rule' % x) for x in ('media', 'page', 'import', 'charset')}
340
341 # User API:
342
343 def parse_stylesheet_file(self, css_file, protocol_encoding=None,
344 linking_encoding=None, document_encoding=None):
345 """Parse a stylesheet from a file or filename.
346
347 Character encoding-related parameters and behavior are the same
348 as in :meth:`parse_stylesheet_bytes`.
349
350 :param css_file:
351 Either a file (any object with a :meth:`~file.read` method)
352 or a filename.
353 :return:
354 A :class:`Stylesheet`.
355
356 """
357 if hasattr(css_file, 'read'):
358 css_bytes = css_file.read()
359 else:
360 with open(css_file, 'rb') as fd:
361 css_bytes = fd.read()
362 return self.parse_stylesheet_bytes(css_bytes, protocol_encoding,
363 linking_encoding, document_encoding)
364
365 def parse_stylesheet_bytes(self, css_bytes, protocol_encoding=None,
366 linking_encoding=None, document_encoding=None):
367 """Parse a stylesheet from a byte string.
368
369 The character encoding is determined from the passed metadata and the
370 ``@charset`` rule in the stylesheet (if any).
371 If no encoding information is available or decoding fails,
372 decoding defaults to UTF-8 and then fall back on ISO-8859-1.
373
374 :param css_bytes:
375 A CSS stylesheet as a byte string.
376 :param protocol_encoding:
377 The "charset" parameter of a "Content-Type" HTTP header (if any),
378 or similar metadata for other protocols.
379 :param linking_encoding:
380 ``<link charset="">`` or other metadata from the linking mechanism
381 (if any)
382 :param document_encoding:
383 Encoding of the referring style sheet or document (if any)
384 :return:
385 A :class:`Stylesheet`.
386
387 """
388 css_unicode, encoding = decode(css_bytes, protocol_encoding,
389 linking_encoding, document_encoding)
390 return self.parse_stylesheet(css_unicode, encoding=encoding)
391
392 def parse_stylesheet(self, css_unicode, encoding=None):
393 """Parse a stylesheet from an Unicode string.
394
395 :param css_unicode:
396 A CSS stylesheet as an unicode string.
397 :param encoding:
398 The character encoding used to decode the stylesheet from bytes,
399 if any.
400 :return:
401 A :class:`Stylesheet`.
402
403 """
404 tokens = tokenize_grouped(css_unicode)
405 if encoding:
406 tokens = _remove_at_charset(tokens)
407 rules, errors = self.parse_rules(tokens, context='stylesheet')
408 return Stylesheet(rules, errors, encoding)
409
410 def parse_style_attr(self, css_source):
411 """Parse a "style" attribute (eg. of an HTML element).
412
413 This method only accepts Unicode as the source (HTML) document
414 is supposed to handle the character encoding.
415
416 :param css_source:
417 The attribute value, as an unicode string.
418 :return:
419 A tuple of the list of valid :class:`Declaration` and
420 a list of :class:`~.parsing.ParseError`.
421 """
422 return self.parse_declaration_list(tokenize_grouped(css_source))
423
424 # API for subclasses:
425
426 def parse_rules(self, tokens, context):
427 """Parse a sequence of rules (rulesets and at-rules).
428
429 :param tokens:
430 An iterable of tokens.
431 :param context:
432 Either ``'stylesheet'`` or an at-keyword such as ``'@media'``.
433 (Most at-rules are only allowed in some contexts.)
434 :return:
435 A tuple of a list of parsed rules and a list of
436 :class:`~.parsing.ParseError`.
437
438 """
439 rules = []
440 errors = []
441 tokens = iter(tokens)
442 for token in tokens:
443 if token.type not in ('S', 'CDO', 'CDC'):
444 try:
445 if token.type == 'ATKEYWORD':
446 rule = self.read_at_rule(token, tokens)
447 result = self.parse_at_rule(
448 rule, rules, errors, context)
449 rules.append(result)
450 else:
451 rule, rule_errors = self.parse_ruleset(token, tokens)
452 rules.append(rule)
453 errors.extend(rule_errors)
454 except ParseError as exc:
455 errors.append(exc)
456 # Skip the entire rule
457 return rules, errors
458
459 def read_at_rule(self, at_keyword_token, tokens):
460 """Read an at-rule from a token stream.
461
462 :param at_keyword_token:
463 The ATKEYWORD token that starts this at-rule
464 You may have read it already to distinguish the rule
465 from a ruleset.
466 :param tokens:
467 An iterator of subsequent tokens. Will be consumed just enough
468 for one at-rule.
469 :return:
470 An unparsed :class:`AtRule`.
471 :raises:
472 :class:`~.parsing.ParseError` if the head is invalid for the core
473 grammar. The body is **not** validated. See :class:`AtRule`.
474
475 """
476 # CSS syntax is case-insensitive
477 at_keyword = at_keyword_token.value.lower()
478 head = []
479 # For the ParseError in case `tokens` is empty:
480 token = at_keyword_token
481 for token in tokens:
482 if token.type in '{;':
483 break
484 # Ignore white space just after the at-keyword.
485 else:
486 head.append(token)
487 # On unexpected end of stylesheet, pretend that a ';' was there
488 head = strip_whitespace(head)
489 for head_token in head:
490 validate_any(head_token, 'at-rule head')
491 body = token.content if token.type == '{' else None
492 return AtRule(at_keyword, head, body,
493 at_keyword_token.line, at_keyword_token.column)
494
495 def parse_at_rule(self, rule, previous_rules, errors, context):
496 """Parse an at-rule.
497
498 Subclasses that override this method must use ``super()`` and
499 pass its return value for at-rules they do not know.
500
501 In CSS 2.1, this method handles @charset, @import, @media and @page
502 rules.
503
504 :param rule:
505 An unparsed :class:`AtRule`.
506 :param previous_rules:
507 The list of at-rules and rulesets that have been parsed so far
508 in this context. This list can be used to decide if the current
509 rule is valid. (For example, @import rules are only allowed
510 before anything but a @charset rule.)
511 :param context:
512 Either ``'stylesheet'`` or an at-keyword such as ``'@media'``.
513 (Most at-rules are only allowed in some contexts.)
514 :raises:
515 :class:`~.parsing.ParseError` if the rule is invalid.
516 :return:
517 A parsed at-rule
518
519 """
520 try:
521 parser = self.at_parsers[rule.at_keyword]
522 except KeyError:
523 raise ParseError(rule, 'unknown at-rule in {0} context: {1}'
524 .format(context, rule.at_keyword))
525 else:
526 return parser(rule, previous_rules, errors, context)
527
528 def parse_page_rule(self, rule, previous_rules, errors, context):
529 if context != 'stylesheet':
530 raise ParseError(rule, '@page rule not allowed in ' + context)
531 selector, specificity = self.parse_page_selector(rule.head)
532 if rule.body is None:
533 raise ParseError(rule,
534 'invalid {0} rule: missing block'.format(rule.at_keyword))
535 declarations, at_rules, rule_errors = \
536 self.parse_declarations_and_at_rules(rule.body, '@page')
537 errors.extend(rule_errors)
538 return PageRule(selector, specificity, declarations, at_rules,
539 rule.line, rule.column)
540
541 def parse_media_rule(self, rule, previous_rules, errors, context):
542 if context != 'stylesheet':
543 raise ParseError(rule, '@media rule not allowed in ' + context)
544 media = self.parse_media(rule.head, errors)
545 if rule.body is None:
546 raise ParseError(rule,
547 'invalid {0} rule: missing block'.format(rule.at_keyword))
548 rules, rule_errors = self.parse_rules(rule.body, '@media')
549 errors.extend(rule_errors)
550 return MediaRule(media, rules, rule.line, rule.column)
551
552 def parse_import_rule(self, rule, previous_rules, errors, context):
553 if context != 'stylesheet':
554 raise ParseError(rule,
555 '@import rule not allowed in ' + context)
556 for previous_rule in previous_rules:
557 if previous_rule.at_keyword not in ('@charset', '@import'):
558 if previous_rule.at_keyword:
559 type_ = 'an {0} rule'.format(previous_rule.at_keyword)
560 else:
561 type_ = 'a ruleset'
562 raise ParseError(previous_rule,
563 '@import rule not allowed after ' + type_)
564 head = rule.head
565 if not head:
566 raise ParseError(rule,
567 'expected URI or STRING for @import rule')
568 if head[0].type not in ('URI', 'STRING'):
569 raise ParseError(rule,
570 'expected URI or STRING for @import rule, got '
571 + head[0].type)
572 uri = head[0].value
573 media = self.parse_media(strip_whitespace(head[1:]), errors)
574 if rule.body is not None:
575 # The position of the ';' token would be best, but we don’t
576 # have it anymore here.
577 raise ParseError(head[-1], "expected ';', got a block")
578 return ImportRule(uri, media, rule.line, rule.column)
579
580 def parse_charset_rule(self, rule, previous_rules, errors, context):
581 raise ParseError(rule, 'mis-placed or malformed @charset rule')
582
583 def parse_media(self, tokens, errors):
584 """For CSS 2.1, parse a list of media types.
585
586 Media Queries are expected to override this.
587
588 :param tokens:
589 A list of tokens
590 :raises:
591 :class:`~.parsing.ParseError` on invalid media types/queries
592 :returns:
593 For CSS 2.1, a list of media types as strings
594 """
595 if not tokens:
596 return ['all']
597 media_types = []
598 for part in split_on_comma(remove_whitespace(tokens)):
599 types = [token.type for token in part]
600 if types == ['IDENT']:
601 media_types.append(part[0].value)
602 else:
603 raise ParseError(tokens[0], 'expected a media type'
604 + ((', got ' + ', '.join(types)) if types else ''))
605 return media_types
606
607 def parse_page_selector(self, tokens):
608 """Parse an @page selector.
609
610 :param tokens:
611 An iterable of token, typically from the ``head`` attribute of
612 an unparsed :class:`AtRule`.
613 :returns:
614 A page selector. For CSS 2.1, this is ``'first'``, ``'left'``,
615 ``'right'`` or ``None``.
616 :raises:
617 :class:`~.parsing.ParseError` on invalid selectors
618
619 """
620 if not tokens:
621 return None, (0, 0)
622 if (len(tokens) == 2 and tokens[0].type == ':'
623 and tokens[1].type == 'IDENT'):
624 pseudo_class = tokens[1].value
625 specificity = {
626 'first': (1, 0), 'left': (0, 1), 'right': (0, 1),
627 }.get(pseudo_class)
628 if specificity:
629 return pseudo_class, specificity
630 raise ParseError(tokens[0], 'invalid @page selector')
631
632 def parse_declarations_and_at_rules(self, tokens, context):
633 """Parse a mixed list of declarations and at rules, as found eg.
634 in the body of an @page rule.
635
636 Note that to add supported at-rules inside @page,
637 :class:`~.page3.CSSPage3Parser` extends :meth:`parse_at_rule`,
638 not this method.
639
640 :param tokens:
641 An iterable of token, typically from the ``body`` attribute of
642 an unparsed :class:`AtRule`.
643 :param context:
644 An at-keyword such as ``'@page'``.
645 (Most at-rules are only allowed in some contexts.)
646 :returns:
647 A tuple of:
648
649 * A list of :class:`Declaration`
650 * A list of parsed at-rules (empty for CSS 2.1)
651 * A list of :class:`~.parsing.ParseError`
652
653 """
654 at_rules = []
655 declarations = []
656 errors = []
657 tokens = iter(tokens)
658 for token in tokens:
659 if token.type == 'ATKEYWORD':
660 try:
661 rule = self.read_at_rule(token, tokens)
662 result = self.parse_at_rule(
663 rule, at_rules, errors, context)
664 at_rules.append(result)
665 except ParseError as err:
666 errors.append(err)
667 elif token.type != 'S':
668 declaration_tokens = []
669 while token and token.type != ';':
670 declaration_tokens.append(token)
671 token = next(tokens, None)
672 if declaration_tokens:
673 try:
674 declarations.append(
675 self.parse_declaration(declaration_tokens))
676 except ParseError as err:
677 errors.append(err)
678 return declarations, at_rules, errors
679
680 def parse_ruleset(self, first_token, tokens):
681 """Parse a ruleset: a selector followed by declaration block.
682
683 :param first_token:
684 The first token of the ruleset (probably of the selector).
685 You may have read it already to distinguish the rule
686 from an at-rule.
687 :param tokens:
688 an iterator of subsequent tokens. Will be consumed just enough
689 for one ruleset.
690 :return:
691 a tuple of a :class:`RuleSet` and an error list.
692 The errors are recovered :class:`~.parsing.ParseError` in declarations.
693 (Parsing continues from the next declaration on such errors.)
694 :raises:
695 :class:`~.parsing.ParseError` if the selector is invalid for the
696 core grammar.
697 Note a that a selector can be valid for the core grammar but
698 not for CSS 2.1 or another level.
699
700 """
701 selector = []
702 for token in chain([first_token], tokens):
703 if token.type == '{':
704 # Parse/validate once we’ve read the whole rule
705 selector = strip_whitespace(selector)
706 if not selector:
707 raise ParseError(first_token, 'empty selector')
708 for selector_token in selector:
709 validate_any(selector_token, 'selector')
710 declarations, errors = self.parse_declaration_list(
711 token.content)
712 ruleset = RuleSet(selector, declarations,
713 first_token.line, first_token.column)
714 return ruleset, errors
715 else:
716 selector.append(token)
717 raise ParseError(token, 'no declaration block found for ruleset')
718
719 def parse_declaration_list(self, tokens):
720 """Parse a ``;`` separated declaration list.
721
722 You may want to use :meth:`parse_declarations_and_at_rules` (or
723 some other method that uses :func:`parse_declaration` directly)
724 instead if you have not just declarations in the same context.
725
726 :param tokens:
727 an iterable of tokens. Should stop at (before) the end
728 of the block, as marked by ``}``.
729 :return:
730 a tuple of the list of valid :class:`Declaration` and a list
731 of :class:`~.parsing.ParseError`
732
733 """
734 # split at ';'
735 parts = []
736 this_part = []
737 for token in tokens:
738 if token.type == ';':
739 parts.append(this_part)
740 this_part = []
741 else:
742 this_part.append(token)
743 parts.append(this_part)
744
745 declarations = []
746 errors = []
747 for tokens in parts:
748 tokens = strip_whitespace(tokens)
749 if tokens:
750 try:
751 declarations.append(self.parse_declaration(tokens))
752 except ParseError as exc:
753 errors.append(exc)
754 # Skip the entire declaration
755 return declarations, errors
756
757 def parse_declaration(self, tokens):
758 """Parse a single declaration.
759
760 :param tokens:
761 an iterable of at least one token. Should stop at (before)
762 the end of the declaration, as marked by a ``;`` or ``}``.
763 Empty declarations (ie. consecutive ``;`` with only white space
764 in-between) should be skipped earlier and not passed to
765 this method.
766 :returns:
767 a :class:`Declaration`
768 :raises:
769 :class:`~.parsing.ParseError` if the tokens do not match the
770 'declaration' production of the core grammar.
771
772 """
773 tokens = iter(tokens)
774
775 name_token = next(tokens) # assume there is at least one
776 if name_token.type == 'IDENT':
777 # CSS syntax is case-insensitive
778 property_name = name_token.value.lower()
779 else:
780 raise ParseError(name_token,
781 'expected a property name, got {0}'.format(name_token.type))
782
783 token = name_token # In case ``tokens`` is now empty
784 for token in tokens:
785 if token.type == ':':
786 break
787 elif token.type != 'S':
788 raise ParseError(
789 token, "expected ':', got {0}".format(token.type))
790 else:
791 raise ParseError(token, "expected ':'")
792
793 value = strip_whitespace(list(tokens))
794 if not value:
795 raise ParseError(token, 'expected a property value')
796 validate_value(value)
797 value, priority = self.parse_value_priority(value)
798 return Declaration(
799 property_name, value, priority, name_token.line, name_token.column)
800
801 def parse_value_priority(self, tokens):
802 """Separate any ``!important`` marker at the end of a property value.
803
804 :param tokens:
805 A list of tokens for the property value.
806 :returns:
807 A tuple of the actual property value (a list of tokens)
808 and the :attr:`~Declaration.priority`.
809 """
810 value = list(tokens)
811 # Walk the token list from the end
812 token = value.pop()
813 if token.type == 'IDENT' and token.value.lower() == 'important':
814 while value:
815 token = value.pop()
816 if token.type == 'DELIM' and token.value == '!':
817 # Skip any white space before the '!'
818 while value and value[-1].type == 'S':
819 value.pop()
820 if not value:
821 raise ParseError(
822 token, 'expected a value before !important')
823 return value, 'important'
824 # Skip white space between '!' and 'important'
825 elif token.type != 'S':
826 break
827 return tokens, None