feature: add bullet and numbered list formatting to paragraphs

Add bullet_type, bullet_char, bullet_auto_number_type, and bullet_font
properties to _Paragraph for programmatic bullet/numbered list creation.

Introduces PP_BULLET_TYPE and PP_AUTO_NUMBER_STYLE enums and models the
bullet choice group (a:buNone, a:buChar, a:buAutoNum) and a:buFont
element on CT_TextParagraphProperties.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MHoroszowski

src/pptx/enum/text.py

@@ -228,3 +228,82 @@ class PP_PARAGRAPH_ALIGNMENT(BaseXmlEnum):
 
 
 PP_ALIGN = PP_PARAGRAPH_ALIGNMENT
+
+
+class PP_BULLET_TYPE(BaseEnum):
+    """Specifies the type of bullet formatting applied to a paragraph.
+
+    Example::
+
+        from pptx.enum.text import PP_BULLET_TYPE
+
+        paragraph.bullet_type = PP_BULLET_TYPE.CHARACTER
+
+    Not a direct MS API mapping; describes the DrawingML bullet choice group.
+    """
+
+    NONE = (1, "No bullet formatting. Uses `a:buNone` element.")
+    """No bullet formatting. Uses `a:buNone` element."""
+
+    CHARACTER = (2, "A character bullet such as '•'. Uses `a:buChar` element.")
+    """A character bullet such as '•'. Uses `a:buChar` element."""
+
+    AUTO_NUMBER = (3, "Auto-numbered bullet. Uses `a:buAutoNum` element.")
+    """Auto-numbered bullet. Uses `a:buAutoNum` element."""
+
+
+class PP_AUTO_NUMBER_STYLE(BaseXmlEnum):
+    """Specifies the auto-number style for a numbered bullet list.
+
+    Example::
+
+        from pptx.enum.text import PP_AUTO_NUMBER_STYLE
+
+        paragraph.bullet_auto_number_type = PP_AUTO_NUMBER_STYLE.ARABIC_PERIOD
+
+    Maps to the `type` attribute of the `a:buAutoNum` element.
+    """
+
+    ARABIC_PERIOD = (1, "arabicPeriod", "Arabic numerals followed by a period: 1. 2. 3.")
+    """Arabic numerals followed by a period: 1. 2. 3."""
+
+    ARABIC_PAREN_RIGHT = (2, "arabicParenR", "Arabic numerals followed by a parenthesis: 1) 2) 3)")
+    """Arabic numerals followed by a parenthesis: 1) 2) 3)"""
+
+    ARABIC_PAREN_BOTH = (3, "arabicParenBoth", "Arabic numerals in parentheses: (1) (2) (3)")
+    """Arabic numerals in parentheses: (1) (2) (3)"""
+
+    ARABIC_PLAIN = (4, "arabicPlain", "Arabic numerals: 1 2 3")
+    """Arabic numerals: 1 2 3"""
+
+    ROMAN_UC_PERIOD = (5, "romanUcPeriod", "Uppercase Roman numerals with period: I. II. III.")
+    """Uppercase Roman numerals with period: I. II. III."""
+
+    ROMAN_LC_PERIOD = (6, "romanLcPeriod", "Lowercase Roman numerals with period: i. ii. iii.")
+    """Lowercase Roman numerals with period: i. ii. iii."""
+
+    ALPHA_UC_PERIOD = (7, "alphaUcPeriod", "Uppercase letters with period: A. B. C.")
+    """Uppercase letters with period: A. B. C."""
+
+    ALPHA_LC_PERIOD = (8, "alphaLcPeriod", "Lowercase letters with period: a. b. c.")
+    """Lowercase letters with period: a. b. c."""
+
+    ALPHA_UC_PAREN_RIGHT = (
+        9, "alphaUcParenR", "Uppercase letters with parenthesis: A) B) C)"
+    )
+    """Uppercase letters with parenthesis: A) B) C)"""
+
+    ALPHA_LC_PAREN_RIGHT = (
+        10, "alphaLcParenR", "Lowercase letters with parenthesis: a) b) c)"
+    )
+    """Lowercase letters with parenthesis: a) b) c)"""
+
+    ALPHA_UC_PAREN_BOTH = (
+        11, "alphaUcParenBoth", "Uppercase letters in parentheses: (A) (B) (C)"
+    )
+    """Uppercase letters in parentheses: (A) (B) (C)"""
+
+    ALPHA_LC_PAREN_BOTH = (
+        12, "alphaLcParenBoth", "Lowercase letters in parentheses: (a) (b) (c)"
+    )
+    """Lowercase letters in parentheses: (a) (b) (c)"""

src/pptx/oxml/text.py

@@ -498,6 +498,18 @@ class CT_TextParagraphProperties(BaseOxmlElement):
     spcAft: CT_TextSpacing | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
         "a:spcAft", successors=_tag_seq[3:]
     )
+    buFont: BaseOxmlElement | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:buFont", successors=_tag_seq[10:]
+    )
+    eg_buTypeface = ZeroOrOneChoice(
+        (
+            Choice("a:buNone"),
+            Choice("a:buAutoNum"),
+            Choice("a:buChar"),
+            Choice("a:buBlip"),
+        ),
+        successors=_tag_seq[14:],
+    )
     defRPr: CT_TextCharacterProperties | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
         "a:defRPr", successors=_tag_seq[16:]
     )

src/pptx/text/text.py

@@ -7,7 +7,13 @@
 from pptx.dml.fill import FillFormat
 from pptx.enum.dml import MSO_FILL
 from pptx.enum.lang import MSO_LANGUAGE_ID
-from pptx.enum.text import MSO_AUTO_SIZE, MSO_UNDERLINE, MSO_VERTICAL_ANCHOR
+from pptx.enum.text import (
+    MSO_AUTO_SIZE,
+    MSO_UNDERLINE,
+    MSO_VERTICAL_ANCHOR,
+    PP_AUTO_NUMBER_STYLE,
+    PP_BULLET_TYPE,
+)
 from pptx.opc.constants import RELATIONSHIP_TYPE as RT
 from pptx.oxml.simpletypes import ST_TextWrappingType
 from pptx.shapes import Subshape
@@ -494,6 +500,113 @@ def alignment(self) -> PP_PARAGRAPH_ALIGNMENT | None:
     def alignment(self, value: PP_PARAGRAPH_ALIGNMENT | None):
         self._pPr.algn = value
 
+    @property
+    def bullet_char(self) -> str | None:
+        """Character used for bullet, e.g. '•'.
+
+        Read/write. Returns |None| if the paragraph does not have a character bullet. Setting this
+        property also sets `bullet_type` to `PP_BULLET_TYPE.CHARACTER`.
+        """
+        pPr = self._p.pPr
+        if pPr is None:
+            return None
+        buChar = pPr.buChar
+        if buChar is None:
+            return None
+        return buChar.get("char")
+
+    @bullet_char.setter
+    def bullet_char(self, value: str | None) -> None:
+        pPr = self._p.get_or_add_pPr()
+        if value is None:
+            pPr._remove_eg_buTypeface()
+            return
+        buChar = pPr.get_or_change_to_buChar()
+        buChar.set("char", value)
+
+    @property
+    def bullet_type(self) -> PP_BULLET_TYPE | None:
+        """Type of bullet formatting on this paragraph.
+
+        Read/write. Returns a member of :ref:`PpBulletType` or |None| if no explicit bullet
+        formatting is set. Assigning |None| removes bullet formatting.
+        """
+        pPr = self._p.pPr
+        if pPr is None:
+            return None
+        bu = pPr.eg_buTypeface
+        if bu is None:
+            return None
+        tag = bu.tag.split("}")[-1]
+        return {
+            "buNone": PP_BULLET_TYPE.NONE,
+            "buChar": PP_BULLET_TYPE.CHARACTER,
+            "buAutoNum": PP_BULLET_TYPE.AUTO_NUMBER,
+        }.get(tag)
+
+    @bullet_type.setter
+    def bullet_type(self, value: PP_BULLET_TYPE | None) -> None:
+        pPr = self._p.get_or_add_pPr()
+        if value is None:
+            pPr._remove_eg_buTypeface()
+            return
+        method_map = {
+            PP_BULLET_TYPE.NONE: "get_or_change_to_buNone",
+            PP_BULLET_TYPE.CHARACTER: "get_or_change_to_buChar",
+            PP_BULLET_TYPE.AUTO_NUMBER: "get_or_change_to_buAutoNum",
+        }
+        getattr(pPr, method_map[value])()
+
+    @property
+    def bullet_auto_number_type(self) -> PP_AUTO_NUMBER_STYLE | None:
+        """Auto-number style for this paragraph's bullet.
+
+        Read/write. Returns a member of :ref:`PpAutoNumberStyle` or |None|. Setting this property
+        also sets `bullet_type` to `PP_BULLET_TYPE.AUTO_NUMBER`.
+        """
+        pPr = self._p.pPr
+        if pPr is None:
+            return None
+        buAutoNum = pPr.buAutoNum
+        if buAutoNum is None:
+            return None
+        type_val = buAutoNum.get("type")
+        if type_val is None:
+            return None
+        return PP_AUTO_NUMBER_STYLE.from_xml(type_val)
+
+    @bullet_auto_number_type.setter
+    def bullet_auto_number_type(self, value: PP_AUTO_NUMBER_STYLE | None) -> None:
+        pPr = self._p.get_or_add_pPr()
+        if value is None:
+            pPr._remove_eg_buTypeface()
+            return
+        buAutoNum = pPr.get_or_change_to_buAutoNum()
+        buAutoNum.set("type", value.xml_value)
+
+    @property
+    def bullet_font(self) -> str | None:
+        """Typeface name for bullet character.
+
+        Read/write. Returns |None| if no explicit bullet font is set.
+        """
+        pPr = self._p.pPr
+        if pPr is None:
+            return None
+        buFont = pPr.buFont
+        if buFont is None:
+            return None
+        return buFont.get("typeface")
+
+    @bullet_font.setter
+    def bullet_font(self, value: str | None) -> None:
+        pPr = self._p.get_or_add_pPr()
+        if value is None:
+            pPr._remove_buFont()
+            return
+        buFont = pPr.get_or_add_buFont()
+        buFont.set("typeface", value)
+
     def clear(self):
         """Remove all content from this paragraph.
 

tests/text/test_text.py

@@ -11,7 +11,7 @@
 from pptx.dml.color import ColorFormat
 from pptx.dml.fill import FillFormat
 from pptx.enum.lang import MSO_LANGUAGE_ID
-from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, MSO_UNDERLINE, PP_ALIGN
+from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, MSO_UNDERLINE, PP_ALIGN, PP_BULLET_TYPE
 from pptx.opc.constants import RELATIONSHIP_TYPE as RT
 from pptx.opc.package import XmlPart
 from pptx.shapes.autoshape import Shape
@@ -807,6 +807,55 @@ def it_can_change_its_horizontal_alignment(self, alignment_set_fixture):
         paragraph.alignment = new_value
         assert paragraph._element.xml == expected_xml
 
+    @pytest.mark.parametrize(
+        ("p_cxml", "expected_value"),
+        [
+            ("a:p", None),
+            ("a:p/a:pPr", None),
+            ("a:p/a:pPr/a:buNone", PP_BULLET_TYPE.NONE),
+            ("a:p/a:pPr/a:buChar{char=-}", PP_BULLET_TYPE.CHARACTER),
+            ("a:p/a:pPr/a:buAutoNum{type=arabicPeriod}", PP_BULLET_TYPE.AUTO_NUMBER),
+        ],
+    )
+    def it_knows_its_bullet_type(self, p_cxml: str, expected_value):
+        paragraph = _Paragraph(element(p_cxml), None)
+        assert paragraph.bullet_type == expected_value
+
+    @pytest.mark.parametrize(
+        ("p_cxml", "value", "expected_tag"),
+        [
+            ("a:p", PP_BULLET_TYPE.CHARACTER, "buChar"),
+            ("a:p", PP_BULLET_TYPE.AUTO_NUMBER, "buAutoNum"),
+            ("a:p", PP_BULLET_TYPE.NONE, "buNone"),
+            ("a:p/a:pPr/a:buChar{char=-}", PP_BULLET_TYPE.NONE, "buNone"),
+        ],
+    )
+    def it_can_change_its_bullet_type(self, p_cxml: str, value, expected_tag: str):
+        p = element(p_cxml)
+        _Paragraph(p, None).bullet_type = value
+        pPr = p.pPr
+        bu = pPr.eg_buTypeface
+        assert bu is not None
+        assert bu.tag.endswith(expected_tag)
+
+    @pytest.mark.parametrize(
+        ("p_cxml", "expected_value"),
+        [
+            ("a:p", None),
+            ("a:p/a:pPr/a:buChar{char=-}", "-"),
+        ],
+    )
+    def it_knows_its_bullet_char(self, p_cxml: str, expected_value: str | None):
+        paragraph = _Paragraph(element(p_cxml), None)
+        assert paragraph.bullet_char == expected_value
+
+    def it_can_set_its_bullet_char(self):
+        p = element("a:p")
+        paragraph = _Paragraph(p, None)
+        paragraph.bullet_char = "-"
+        assert paragraph.bullet_type == PP_BULLET_TYPE.CHARACTER
+        assert paragraph.bullet_char == "-"
+
     def it_can_clear_itself_of_content(self, clear_fixture):
         paragraph, expected_xml = clear_fixture
         paragraph.clear()