k3fnmatch

Enhanced fnmatch with grouping regex and path transformation utilities.

k3fnmatch is a component of pykit3 project: a python3 toolkit set.

Features

Enhanced pattern matching: Supports ** for multi-segment paths
Grouping regex: Captures matched segments for extraction
Path transformation: Convert paths using pattern pairs
Drop-in enhancement: Compatible with standard fnmatch patterns

Installation

pip install k3fnmatch

Quick Start

Pattern Matching with translate()

Convert fnmatch patterns to regex with capture groups:

import re
import k3fnmatch

# Match files in any subdirectory
pattern = k3fnmatch.translate("**/*.md")
regex = re.compile(pattern)

# Extract matched segments
match = regex.match("docs/guide/intro.md")
print(match.groups())  # ('docs/guide/', 'intro', '.md')

Path Transformation with fnmap()

Transform paths using source and destination patterns:

import k3fnmatch

# Convert .md to .html
result = k3fnmatch.fnmap(
    "docs/guide/intro.md",
    "**/*.md",
    "**/*.html"
)
print(result)  # "docs/guide/intro.html"

# Add suffix to filenames
result = k3fnmatch.fnmap(
    "src/module.py",
    "*/*.py",
    "*/*-backup.py"
)
print(result)  # "src/module-backup.py"

Pattern Syntax

Pattern	Meaning	Example
`*`	Single segment (no `/`)	`*.txt` matches `file.txt` but not `dir/file.txt`
`**`	Multi-segment (with `/`)	`*/.py` matches `a/b/c.py`
`?`	Single character	`file?.txt` matches `file1.txt`
`[...]`	Character class	`[abc]` matches `a`, `b`, or `c`
`[!...]`	Negated class	`[!0-9]` matches non-digits

API Reference

`k3fnmatch.pattern`

`fnmap(src_path, src_pattern, dst_pattern)`

Transform a path using source and destination patterns.

Matches src_path against src_pattern, extracts the wildcard segments, and reconstructs using dst_pattern with the same wildcards in corresponding positions.

Parameters:

Name	Type	Description	Default
`src_path`	`str`	Path to transform (e.g., "foo/x/y.md")	required
`src_pattern`	`str`	Source pattern with wildcards (e.g., "*/.md")	required
`dst_pattern`	`str`	Destination pattern with wildcards (e.g., "*/-cn.md")	required

Returns:

Type	Description
`str`	Transformed path (e.g., "foo/x/y-cn.md")

Examples:

>>> fnmap("foo/x/y.md", "**/*.md", "**/*-cn.md")
'foo/x/y-cn.md'

>>> fnmap("a/b/c.txt", "*/*/*.txt", "*/*/*-backup.txt")
'a/b/c-backup.txt'

>>> fnmap("file.md", "*.md", "*-backup.md")
'file-backup.md'

Source code in k3fnmatch/pattern.py

def fnmap(src_path: str, src_pattern: str, dst_pattern: str) -> str:
    """Transform a path using source and destination patterns.

    Matches src_path against src_pattern, extracts the wildcard segments,
    and reconstructs using dst_pattern with the same wildcards in corresponding
    positions.

    Args:
        src_path: Path to transform (e.g., "foo/x/y.md")
        src_pattern: Source pattern with wildcards (e.g., "**/*.md")
        dst_pattern: Destination pattern with wildcards (e.g., "**/*-cn.md")

    Returns:
        Transformed path (e.g., "foo/x/y-cn.md")

    Examples:
        >>> fnmap("foo/x/y.md", "**/*.md", "**/*-cn.md")
        'foo/x/y-cn.md'

        >>> fnmap("a/b/c.txt", "*/*/*.txt", "*/*/*-backup.txt")
        'a/b/c-backup.txt'

        >>> fnmap("file.md", "*.md", "*-backup.md")
        'file-backup.md'
    """
    regex = translate(src_pattern)

    dst_parts = re.split(r"([*]+)", dst_pattern)

    src_parts = re.split(regex, src_path)

    # strip two empty string produced.
    src_parts = src_parts[1:-1]

    #  (?s:(foo/)(?>(.*?)(/d/))(.*)(\.md))\Z
    #  src_parts:     ['foo/', 'x/y/z', '/d/', 'bar', '.md']
    #  dst_parts: ['bar/', '**', '/d/', '*', '.cn.md']
    #
    #  Replace non-wildcard part with the corresponding one in the dst_parts

    res: list[str] = []
    for i, p in enumerate(src_parts):
        if dst_parts[i] in ("**", "*"):
            res.append(p)
        else:
            res.append(dst_parts[i])

    return "".join(res)

`translate(pat)`

Translate a shell PATTERN to a regular expression with grouping.

Enhanced version of fnmatch.translate() that: - Produces grouping regex for capturing matched segments - Supports ** for multi-segment matching (matches across /) - Supports * for single-segment matching (no /) - Supports ? for single character - Supports [...] for character classes - Supports backslash escaping: *, \?, [, ], \