Source code for docx.styles.styles

"""Styles object, container for all objects in the styles part."""

from __future__ import annotations

from warnings import warn

from import WD_STYLE_TYPE
from docx.oxml.styles import CT_Styles
from docx.shared import ElementProxy
from docx.styles import BabelFish
from docx.styles.latent import LatentStyles
from import BaseStyle, StyleFactory

[docs]class Styles(ElementProxy): """Provides access to the styles defined in a document. Accessed using the :attr:`.Document.styles` property. Supports ``len()``, iteration, and dictionary-style access by style name. """ def __init__(self, styles: CT_Styles): super().__init__(styles) self._element = styles def __contains__(self, name): """Enables `in` operator on style name.""" internal_name = BabelFish.ui2internal(name) return any(style.name_val == internal_name for style in self._element.style_lst) def __getitem__(self, key: str): """Enables dictionary-style access by UI name. Lookup by style id is deprecated, triggers a warning, and will be removed in a near-future release. """ style_elm = self._element.get_by_name(BabelFish.ui2internal(key)) if style_elm is not None: return StyleFactory(style_elm) style_elm = self._element.get_by_id(key) if style_elm is not None: msg = ( "style lookup by style_id is deprecated. Use style name as " "key instead." ) warn(msg, UserWarning, stacklevel=2) return StyleFactory(style_elm) raise KeyError("no style with name '%s'" % key) def __iter__(self): return (StyleFactory(style) for style in self._element.style_lst) def __len__(self): return len(self._element.style_lst)
[docs] def add_style(self, name, style_type, builtin=False): """Return a newly added style object of `style_type` and identified by `name`. A builtin style can be defined by passing True for the optional `builtin` argument. """ style_name = BabelFish.ui2internal(name) if style_name in self: raise ValueError("document already contains style '%s'" % name) style = self._element.add_style_of_type(style_name, style_type, builtin) return StyleFactory(style)
[docs] def default(self, style_type: WD_STYLE_TYPE): """Return the default style for `style_type` or |None| if no default is defined for that type (not common).""" style = self._element.default_for(style_type) if style is None: return None return StyleFactory(style)
def get_by_id(self, style_id: str | None, style_type: WD_STYLE_TYPE): """Return the style of `style_type` matching `style_id`. Returns the default for `style_type` if `style_id` is not found or is |None|, or if the style having `style_id` is not of `style_type`. """ if style_id is None: return self.default(style_type) return self._get_by_id(style_id, style_type) def get_style_id(self, style_or_name, style_type): """Return the id of the style corresponding to `style_or_name`, or |None| if `style_or_name` is |None|. If `style_or_name` is not a style object, the style is looked up using `style_or_name` as a style name, raising |ValueError| if no style with that name is defined. Raises |ValueError| if the target style is not of `style_type`. """ if style_or_name is None: return None elif isinstance(style_or_name, BaseStyle): return self._get_style_id_from_style(style_or_name, style_type) else: return self._get_style_id_from_name(style_or_name, style_type) @property def latent_styles(self): """A |LatentStyles| object providing access to the default behaviors for latent styles and the collection of |_LatentStyle| objects that define overrides of those defaults for a particular named latent style.""" return LatentStyles(self._element.get_or_add_latentStyles()) def _get_by_id(self, style_id: str | None, style_type: WD_STYLE_TYPE): """Return the style of `style_type` matching `style_id`. Returns the default for `style_type` if `style_id` is not found or if the style having `style_id` is not of `style_type`. """ style = self._element.get_by_id(style_id) if style_id else None if style is None or style.type != style_type: return self.default(style_type) return StyleFactory(style) def _get_style_id_from_name( self, style_name: str, style_type: WD_STYLE_TYPE ) -> str | None: """Return the id of the style of `style_type` corresponding to `style_name`. Returns |None| if that style is the default style for `style_type`. Raises |ValueError| if the named style is not found in the document or does not match `style_type`. """ return self._get_style_id_from_style(self[style_name], style_type) def _get_style_id_from_style( self, style: BaseStyle, style_type: WD_STYLE_TYPE ) -> str | None: """Id of `style`, or |None| if it is the default style of `style_type`. Raises |ValueError| if style is not of `style_type`. """ if style.type != style_type: raise ValueError( "assigned style is type %s, need type %s" % (style.type, style_type) ) if style == self.default(style_type): return None return style.style_id