导航|地址|刷新
glob patterns - Python Packaging User Gu…
ContentsMenuExpandLight modeDark modeAuto light/dark, in light modeAuto light/dark, in dark mode
Hide navigation sidebar

Hide table of contents sidebar
Skip to content

Toggle site navigation sidebar

Python Packaging User Guide

Toggle Light / Dark / Auto color theme

Toggle table of contents sidebar

Python Packaging User Guide

Overview of Python Packaging

The Packaging Flow

Tutorials
Toggle navigation of Tutorials

Installing Packages

Managing Application Dependencies

Packaging Python Projects

Guides
Toggle navigation of Guides

Installation
Toggle navigation of Installation

Install packages in a virtual environment using pip and venv

Installing packages using virtualenv

Installing stand alone command line tools

Installing pip/setuptools/wheel with Linux Package Managers

Installing scientific packages

Building and Publishing
Toggle navigation of Building and Publishing

Writing your pyproject.toml

Packaging and distributing projects

Dropping support for older Python versions

Packaging binary extensions

Packaging namespace packages

Creating and packaging command-line tools

Creating and discovering plugins

Using TestPyPI

Making a PyPI-friendly README

Publishing package distribution releases using GitHub Actions CI/CD workflows

How to modernize a setup.py based project?

Licensing examples and user scenarios

Hosting
Toggle navigation of Hosting

Package index mirrors and caches

Hosting your own simple repository

Tool recommendations

Analyzing PyPI package downloads

Discussions
Toggle navigation of Discussions

Versioning

Deploying Python applications

pip vs easy_install

install_requires vs requirements files

Distribution package vs. import package

Package Formats

src layout vs flat layout

Is setup.py deprecated?

Single-sourcing the Project Version

Supporting downstream packaging

PyPA specifications
Toggle navigation of PyPA specifications

Package Distribution Metadata
Toggle navigation of Package Distribution Metadata

Names and normalization

Core metadata specifications

Version specifiers

Dependency specifiers

pyproject.toml specification

Dependency Groups

Inline script metadata

Platform compatibility tags

Well-known Project URLs in Metadata

glob patterns

License Expression

Package Installation Metadata
Toggle navigation of Package Installation Metadata

Recording installed projects

Entry points specification

Recording the Direct URL Origin of installed distributions

Direct URL Data Structure

Python Virtual Environments

Externally Managed Environments

Package Distribution File Formats
Toggle navigation of Package Distribution File Formats

Source distribution format

Binary distribution format

Package Index Interfaces
Toggle navigation of Package Index Interfaces

The .pypirc file

Simple repository API

File Yanking

Index hosted attestations

Project Status Markers

Python Description Formats
Toggle navigation of Python Description Formats

build-details.json
Toggle navigation of build-details.json

v1.0

Reproducible Environments
Toggle navigation of Reproducible Environments

pylock.toml Specification

PyPA schemas

Project Summaries

Glossary

How to Get Support

Contribute to this guide

News

Back to top

View this page

Edit this page

Toggle Light / Dark / Auto color theme

Toggle table of contents sidebar

glob patterns¶

Some PyPA specifications, e.g. pyproject.toml’s license-files, accept certain types of glob patterns to match a given string containing wildcards and character ranges against files and directories. This specification defines which patterns are acceptable and how they should be handled.

Valid glob patterns¶

For PyPA purposes, a valid glob pattern MUST be a string matched against filesystem entries as specified below:

Alphanumeric characters, spaces (`` ),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 to relative paths, e.g., when used in pyproject.toml, patterns should always be relative 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 are invalid. 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 they can also be defined.

Tools consuming glob patterns:

MUST treat each value as a glob pattern, and MUST raise an error if the pattern contains invalid glob syntax.

MUST raise an error if any individual user-specified pattern does not match at 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

Reference implementation in Python¶

It is possible to defer the majority of the pattern matching against the file system to the glob module in Python’s standard library. It is necessary however 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

History¶

January 2025: Initial version

March 2026: Treat spaces as a verbatim character

Next

License Expression

Previous

Well-known Project URLs in Metadata

Copyright © 2013–2020, PyPA
Made with Sphinx and @pradyunsg's Furo
Last updated on Jul 29, 2026

On this page

glob patterns
Valid glob patterns

Reference implementation in Python

History

------
导航页打开网址