puku-markdown 0.1.0__tar.gz

puku_markdown-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,99 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      use_testpypi:
+        description: 'Publish to TestPyPI instead of PyPI'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate source branch and destination
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branch and destination compatibility
+        run: |
+          BRANCH="${{ github.ref_name }}"
+          USE_TEST="${{ inputs.use_testpypi }}"
+          EVENT="${{ github.event_name }}"
+
+          if [[ "$USE_TEST" == "true" ]]; then
+            echo "✅ Publishing to TestPyPI - branch $BRANCH is allowed."
+            exit 0
+          fi
+
+          if [[ "$BRANCH" != "main" && "$EVENT" != "release" ]]; then
+            echo "❌ Error: Publishing to PyPI is only allowed from the 'main' branch or a release tag."
+            echo "Current branch: $BRANCH, event: $EVENT"
+            exit 1
+          fi
+
+          echo "✅ Validation passed - publishing to PyPI from $BRANCH (event: $EVENT)."
+
+  test:
+    name: Run pytest suite
+    needs: validate
+    uses: ./.github/workflows/pytest.yaml
+    secrets: inherit
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          retention-days: 1
+
+  publish:
+    name: Publish to ${{ inputs.use_testpypi && 'TestPyPI' || 'PyPI' }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ inputs.use_testpypi && 'testpypi' || 'pypi' }}
+      url: ${{ inputs.use_testpypi && 'https://test.pypi.org/project/puku-markdown' || 'https://pypi.org/project/puku-markdown' }}
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to TestPyPI (with API token)
+        if: inputs.use_testpypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+      - name: Publish to PyPI (with API token)
+        if: ${{ !inputs.use_testpypi }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          password: ${{ secrets.PYPI_API_TOKEN }}

puku_markdown-0.1.0/.github/workflows/pytest.yaml

@@ -0,0 +1,41 @@
+name: Pytest
+
+on:
+  workflow_call:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies (including test group)
+        run: uv sync --group test
+
+      - name: Run pytest with coverage monitoring
+        run: uv run pytest --cov --cov-report=term-missing

puku_markdown-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__local__/
+__pycache__
+.pytest_cache/
+.venv/
+.coverage

puku_markdown-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: puku-markdown
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12

puku_markdown-0.1.0/puku_markdown/_utils/constants.py

@@ -0,0 +1,315 @@
+"""
+CommonMark constants for Markdown parsing.
+
+Coding style note:
+    Typically, names are limited to at most 4 words (e.g., `INDENTED_CODE_BLOCK_MIN_INDENT`).
+    However, for constants that directly represent a CommonMark element (e.g., fenced code
+    blocks, thematic breaks), the element name in the prefix (e.g., `FENCED_CODE_BLOCK_`,
+    `THEMATIC_BREAK_`) is **excluded** from the word count. This allows longer, more
+    precise names without violating the spirit of the rule.
+
+    This exception is *temporary* and subject to revision.
+
+    TODO: Re-evaluate the word-limit exception for CommonMark element prefixes.
+          Consider adopting a fixed maximum total length or a different scheme.
+"""
+
+from typing import Final
+
+
+COMMONMARK_TAB_STOP: Final[int] = 4
+"""Number of spaces to which a tab character expands in CommonMark parsing.
+
+See Also:
+    CommonMark Spec 0.31.2, Section 2.2 (Tabs):
+    https://spec.commonmark.org/0.31.2/#tabs
+"""
+
+NULL_CHARACTER: Final[str] = "\0"
+
+HASH_CHARACTER: Final[str] = "#"
+"""
+Hash/number sign character used as the ATX heading marker in CommonMark.
+"""
+
+LESS_THAN_CHARACTER: Final[str] = "<"
+"""
+The less-than sign character '<' (Unicode U+003C).
+"""
+
+GREATER_THAN_CHARACTER: Final[str] = ">"
+"""The greater-than sign character '>' (Unicode U+003E).
+"""
+
+SPACE_CHARACTER: Final[str] = " "
+"""
+The space character ' ' (Unicode U+0020).
+"""
+
+TAB_CHARACTER: Final[str] = "\t"
+"""
+The tab character '\\t' (Unicode U+0009, CHARACTER TABULATION).
+"""
+
+LEFT_SQUARE_BRACKET_CHARACTER: Final[str] = "["
+"""
+The left square bracket character '[' (Unicode U+005B, LEFT SQUARE BRACKET).
+"""
+
+RIGHT_SQUARE_BRACKET_CHARACTER: Final[str] = "]"
+"""
+The right square bracket character ']' (Unicode U+005D, RIGHT SQUARE BRACKET).
+"""
+
+LINE_FEED_CHARACTER: Final[str] = "\n"
+"""
+Line feed (LF), the '\n' character.
+"""
+
+BACKSLASH_CHARACTER: Final[str] = "\\"
+"""
+Backslash, the escape character.
+"""
+
+COLON_CHARACTER: Final[str] = ":"
+"""
+Colon (:), used in reference definitions after the label.
+"""
+
+LEFT_PARENTHESIS_CHARACTER: Final[str] = "("
+"""
+Left parenthesis '(' (U+0028).
+"""
+
+RIGHT_PARENTHESIS_CHARACTER: Final[str] = ")"
+"""
+Right parenthesis ')' (U+0029).
+"""
+
+UNICODE_REPLACEMENT_CHARACTER: Final[str] = "\ufffd"
+
+BACKTICK_CHARACTER: Final[str] = "`"
+
+INDENTED_CODE_BLOCK_MIN_INDENT: Final[int] = 4
+"""Minimum indentation required for a line to be part of an indented code block.
+
+According to the CommonMark specification (Section 4.4), an indented chunk is a
+sequence of non-blank lines, each preceded by *four or more spaces* of indentation.
+Lines meeting this threshold form an indented code block.
+
+Note:
+    An indented code block cannot interrupt a paragraph. Therefore, within a
+    paragraph, a line with indentation >= this value is treated as a lazy
+    continuation of the paragraph, not as a new code block.
+
+See Also:
+    CommonMark Spec 0.31.2, Section 4.4:
+    https://spec.commonmark.org/0.31.2/#indented-code-blocks
+"""
+
+THEMATIC_BREAK_MARKERS: Final[frozenset[str]] = frozenset({"*", "-", "_"})
+"""
+Immutable set of characters that can initiate a CommonMark thematic break.
+"""
+
+THEMATIC_BREAK_MIN_MARKER_COUNT: Final[int] = 3
+"""
+Minimum number of identical markers required for a CommonMark thematic break.
+
+See CommonMark Spec 0.31.2, Section 4.1:
+https://spec.commonmark.org/0.31.2/#thematic-breaks
+"""
+
+FENCED_CODE_BLOCK_MIN_MARKER_COUNT: Final[int] = 3
+"""
+Minimum number of consecutive backticks or tildes required for a fenced code block.
+
+Per CommonMark Spec 0.31.2, Section 4.5:
+https://spec.commonmark.org/0.31.2/#fenced-code-blocks
+"""
+
+FENCED_CODE_BLOCK_MARKERS: Final[frozenset[str]] = frozenset({"~", "`"})
+"""
+Immutable set of marker characters that can open a fenced code block.
+
+See Also:
+    CommonMark Spec 0.31.2, Section 4.5:
+    https://spec.commonmark.org/0.31.2/#fenced-code-blocks
+"""
+
+ATX_HEADING_MAX_LEVEL: Final[int] = 6
+"""
+Maximum heading level for an ATX heading, corresponding to six '#' characters.
+
+See Also:
+    CommonMark Spec 0.31.2, Section 4.2 (ATX headings):
+    https://spec.commonmark.org/0.31.2/#atx-headings
+"""
+
+HTML_BLOCK_NAMES: Final[tuple[str, ...]] = (
+    "address",
+    "article",
+    "aside",
+    "base",
+    "basefont",
+    "blockquote",
+    "body",
+    "caption",
+    "center",
+    "col",
+    "colgroup",
+    "dd",
+    "details",
+    "dialog",
+    "dir",
+    "div",
+    "dl",
+    "dt",
+    "fieldset",
+    "figcaption",
+    "figure",
+    "footer",
+    "form",
+    "frame",
+    "frameset",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "hr",
+    "html",
+    "iframe",
+    "legend",
+    "li",
+    "link",
+    "main",
+    "menu",
+    "menuitem",
+    "nav",
+    "noframes",
+    "ol",
+    "optgroup",
+    "option",
+    "p",
+    "param",
+    "search",
+    "section",
+    "summary",
+    "table",
+    "tbody",
+    "td",
+    "tfoot",
+    "th",
+    "thead",
+    "title",
+    "tr",
+    "track",
+    "ul",
+)
+"""
+List of HTML block-level tag names as defined by the CommonMark specification.
+
+This list is used to construct the regex for matching block-level HTML tags
+(CommonMark HTML block type 6). The tags are matched case-insensitively
+(using `re.IGNORECASE` flag) because HTML tag names are case-insensitive.
+
+Reference: https://spec.commonmark.org/0.31.2/#html-blocks
+"""
+
+SETEXT_HEADING_MARKERS: Final[frozenset[str]] = frozenset({"-", "="})
+"""Markers that denote Setext headings (CommonMark section 4.2, version 0.31.2).
+
+A line consisting entirely of `=` characters (optionally with trailing spaces)
+indicates a level-1 heading. A line consisting entirely of `-` characters
+indicates a level-2 heading. The marker line must appear immediately after the
+heading text (with no blank line in between).
+
+Reference: https://spec.commonmark.org/0.31.2/#setext-headings
+"""
+
+HYPHEN_MINUS_CHARACTER: Final[str] = "-"
+"""
+The hyphen-minus character '-' (Unicode U+002D).
+
+This character is used as a hyphen, minus sign, or dash. In Markdown,
+it appears in Setext headings (level-2), unordered lists, and horizontal rules.
+"""
+
+EQUALS_SIGN_CHARACTER: Final[str] = "="
+"""
+The equals sign '=' (Unicode U+003D).
+
+In Markdown, this character is used in Setext headings (level-1) and as a
+delimiter for fenced code blocks (with backticks). It also appears in
+HTML attributes and link definitions.
+"""
+
+MAX_LINK_DESTINATION_PARENTHESIS_DEPTH: Final[int] = 32
+"""
+Maximum allowed nesting depth of parentheses inside a bare link destination
+(i.e., when not enclosed in `<` `>`). Exceeding this limit invalidates the
+link destination and stops scanning.
+
+This limit is a safety measure against pathological input; it is not mandated
+by the CommonMark specification, which only requires balanced parentheses.
+The value 32 is high enough for all practical URLs yet low enough to prevent
+excessive CPU consumption.
+"""
+
+DOUBLE_QUOTE_CHARACTER: Final[str] = '"'
+"""
+Double quotation mark " (U+0022).
+"""
+
+SINGLE_QUOTE_CHARACTER: Final[str] = "'"
+"""
+Apostrophe / single quote ' (U+0027).
+"""
+
+BULLET_LIST_MARKERS: Final[frozenset[str]] = frozenset({"*", "-", "+"})
+"""Bullet list markers as defined in CommonMark section 5.2 (version 0.31.2).
+
+A line beginning with one of these characters, followed by a space or tab,
+starts a bullet list item. The marker may be preceded by up to three spaces
+of indentation.
+
+References:
+- https://spec.commonmark.org/0.31.2/#list-items
+- https://spec.commonmark.org/0.31.2/#bullet-list-marker
+"""
+
+ORDERED_LIST_MARKER_DELIMITERS: Final[frozenset[str]] = frozenset({".", ")"})
+"""Ordered list marker delimiters as defined in CommonMark section 5.2 (version 0.31.2).
+
+An ordered list marker consists of a positive integer followed by a delimiter
+character: either a period (`.`) or a right parenthesis (`)`). This constant
+holds the two allowed delimiter characters.
+
+Reference: https://spec.commonmark.org/0.31.2/#list-items
+"""
+
+EMPTY_STRING: str = ""
+"""An immutable sentinel representing the empty string.
+
+Use this constant instead of the literal `""` when the empty string serves as
+a default value, a placeholder, or a well-known marker in public APIs or
+repeated logic. This improves readability and centralises the concept.
+"""
+
+MAX_ORDERED_LIST_MARKER_DIGITS: int = 9
+"""
+The maximum number of digits permitted in an ordered list marker.
+
+The CommonMark Spec (0.30+) limits ordered list markers (e.g., '1.', '999999999.')
+to at most 9 digits. This limit prevents integer overflows in browsers that use
+signed 32-bit integers for list indexing.
+
+Any marker exceeding this length (e.g., '1000000000.') is invalid and must not
+be recognized as a list marker by a conforming implementation.
+
+Source: CommonMark Spec 0.30, Section 5.2 - List Items.
+"""

puku_markdown-0.1.0/puku_markdown/_utils/metrics.py

@@ -0,0 +1,26 @@
+from puku_markdown._utils.constants import COMMONMARK_TAB_STOP, TAB_CHARACTER
+
+
+def commonmark_char_width(start_colno: int, character: str) -> int:
+    """
+    Return the visual width (in columns) of a character, as defined by CommonMark.
+
+    For a tab character, the width is the number of spaces required to advance
+    the visual column from `start_colno` to the next tab stop (every 4 columns).
+    For any other character, the width is 1.
+
+    Args:
+        start_colno: The visual column index where the character begins (0-based).
+        character: The character to measure.
+
+    Returns:
+        The visual width increment that the character contributes.
+
+    Reference:
+        https://spec.commonmark.org/0.31.2/#tabs
+    """
+    return (
+        (COMMONMARK_TAB_STOP - (start_colno % COMMONMARK_TAB_STOP))
+        if character == TAB_CHARACTER
+        else 1
+    )

puku_markdown-0.1.0/puku_markdown/_utils/predicates.py

@@ -0,0 +1,38 @@
+from puku_markdown._utils.constants import TAB_CHARACTER, SPACE_CHARACTER
+
+
+def is_space_or_tab(character: str) -> bool:
+    """
+    Return True if char is ASCII space (U+0020) or tab (U+0009).
+
+    In CommonMark, only these two characters affect indentation for block structure.
+    Other Unicode whitespace characters (e.g., non-breaking space) do not count as
+    leading indentation and are treated as regular content.
+
+    Reference: https://spec.commonmark.org/0.31.2/#tabs
+    """
+    return character in (TAB_CHARACTER, SPACE_CHARACTER)
+
+
+def is_ascii_control(character: str) -> bool:
+    """
+    Return True if the character is an ASCII control character.
+
+    This includes C0 control codes (U+0000-U+001F) and DEL (U+007F).
+    These characters are generally not allowed in plain text and
+    terminate link destinations or titles in CommonMark.
+    """
+    code = ord(character)
+    return code < 0x20 or code == 0x7F
+
+
+def is_ascii_digit(character: str) -> bool:
+    """
+    Return True if the character is an ASCII digit (U+0030-U+0039).
+
+    This is equivalent to `'0' <= character <= '9'` and is the most
+    readable and performant way to test for ASCII digits.
+
+    Reference: https://spec.commonmark.org/0.31.2/#list-items
+    """
+    return "0" <= character <= "9"