pyproject.tomlsetup.py based project?glob patterns¶Some PyPA specifications, e.g.pyproject.toml’s license-files, accept certain types ofglob patternsto match a given string containing wildcards and character ranges againstfiles and directories. This specification defines which patterns are acceptableand how they should be handled.
For PyPA purposes, avalid glob pattern MUST be a string matched againstfilesystem entries as specified below:
Alphanumeric characters, underscores (_), hyphens (-) and dots (.)MUST be matched verbatim.
Special glob characters:*,?,** and character ranges:[]containing only the verbatim matched characters MUST be supported.Within[...], the hyphen indicates a locale-agnostic range (e.g.a-z,order based on Unicode code points).Hyphens at the start or end are matched literally.
Path delimiters MUST be the forward slash character (/).
Patterns always refer torelative paths,e.g., when used inpyproject.toml, patterns should always berelative to the directory containing that file.Therefore the leading slash character MUST NOT be used.
Parent directory indicators (..) MUST NOT be used.
Any characters or character sequences not covered by this specification areinvalid. Projects MUST NOT use such values.Tools consuming glob patterns SHOULD reject invalid values with an error.
Literal paths (e.g.LICENSE) are valid globs which means theycan also be defined.
Tools consuming glob patterns:
MUST treat each value as a glob pattern, and MUST raise an error if thepattern contains invalid glob syntax.
MUST raise an error if any individual user-specified pattern does not matchat least one file.
Examples of valid glob patterns:
"LICEN[CS]E*""AUTHORS*""licenses/LICENSE.MIT""licenses/LICENSE.CC0""LICENSE.txt""licenses/*"
Examples of invalid glob patterns:
"..\LICENSE.MIT"# .. must not be used.# \ is an invalid path delimiter, / must be used."LICEN{CSE*"# the { character is not allowed
It is possible to defer the majority of the pattern matching against the filesystem to theglob module in Python’s standard library. It is necessaryhowever to perform additional validations.
The code below is as a simple reference implementation:
importosimportrefromglobimportglobdeffind_pattern(pattern:str)->list[str]:""" >>> find_pattern("/LICENSE.MIT") Traceback (most recent call last): ... ValueError: Pattern '/LICENSE.MIT' should be relative... >>> find_pattern("../LICENSE.MIT") Traceback (most recent call last): ... ValueError: Pattern '../LICENSE.MIT' cannot contain '..'... >>> find_pattern("LICEN{CSE*") Traceback (most recent call last): ... ValueError: Pattern 'LICEN{CSE*' contains invalid characters... """if".."inpattern:raiseValueError(f"Pattern{pattern!r} cannot contain '..'")ifpattern.startswith((os.sep,"/"))or":\\"inpattern:raiseValueError(f"Pattern{pattern!r} should be relative and must not start with '/'")ifre.match(r'^[\w\-\.\/\*\?\[\]]+$',pattern)isNone:raiseValueError(f"Pattern '{pattern}' contains invalid characters.")found=glob(pattern,recursive=True)ifnotfound:raiseValueError(f"Pattern '{pattern}' did not match any files.")returnfound