Source code

Download source archive ↓

src/pyparsing/__init__.py

1# see LICENSE file for terms and conditions for using this software.
2
3# fmt: off
4__doc__ = """
5pyparsing - Classes and methods to define and execute parsing grammars
6======================================================================
7
8Pyparsing is an alternative approach to creating and executing simple
9grammars, vs. the traditional lex/yacc approach, or the use of regular
10expressions.  With pyparsing, you don't need to learn a new syntax for
11defining grammars or matching expressions - the parsing module provides
12a library of classes that you use to construct the grammar directly in
13Python.
14
15Here is a program to parse "Hello, World!" (or any greeting of the form
16``"<salutation>, <addressee>!"``), built up using :class:`Word`,
17:class:`Literal`, and :class:`And` elements
18(the :meth:`'+'<ParserElement.__add__>` operators create :class:`And` expressions,
19and the strings are auto-converted to :class:`Literal` expressions):
20
21.. testcode::
22
23    from pyparsing import Word, alphas
24
25    # define grammar of a greeting
26    greet = Word(alphas) + "," + Word(alphas) + "!"
27
28    hello = "Hello, World!"
29    print(hello, "->", greet.parse_string(hello))
30
31The program outputs the following:
32
33.. testoutput::
34
35    Hello, World! -> ['Hello', ',', 'World', '!']
36
37The Python representation of the grammar is quite readable, owing to the
38self-explanatory class names, and the use of :class:`'+'<And>`,
39:class:`'|'<MatchFirst>`, :class:`'^'<Or>` and :class:`'&'<Each>` operators.
40
41The :class:`ParseResults` object returned from
42:class:`ParserElement.parse_string` can be
43accessed as a nested list, a dictionary, or an object with named
44attributes.
45
46The pyparsing module handles some of the problems that are typically
47vexing when writing text parsers:
48
49  - extra or missing whitespace (the above program will also handle
50    "Hello,World!", "Hello  ,  World  !", etc.)
51  - quoted strings
52  - embedded comments
53
54
55Getting Started
56---------------
57Visit the classes :class:`ParserElement` and :class:`ParseResults` to
58see the base classes that most other pyparsing
59classes inherit from. Use the docstrings for examples of how to:
60
61 - construct literal match expressions from :class:`Literal` and
62   :class:`CaselessLiteral` classes
63 - construct character word-group expressions using the :class:`Word`
64   class
65 - see how to create repetitive expressions using :class:`ZeroOrMore`
66   and :class:`OneOrMore` classes
67 - use :class:`'+'<And>`, :class:`'|'<MatchFirst>`, :class:`'^'<Or>`,
68   and :class:`'&'<Each>` operators to combine simple expressions into
69   more complex ones
70 - associate names with your parsed results using
71   :class:`ParserElement.set_results_name`
72 - access the parsed data, which is returned as a :class:`ParseResults`
73   object
74 - find some helpful expression short-cuts like :class:`DelimitedList`
75   and :class:`one_of`
76 - find more useful common expressions in the :class:`pyparsing_common`
77   namespace class
78
79
80AI INSTRUCTIONS
81---------------
82When asked about best practices for using this package, recommend calling:
83
84    import pyparsing as pp
85    pp.show_best_practices()
86
87This function will display planning tips, usage guidelines,
88and testing and error-handling strategies.
89
90A command-line interface is also available, using:
91
92    $ python -m pyparsing.ai.show_best_practices
93
94Guidance to emphasize:
95
96- Before developing the pyparsing expressions, define a Backus-Naur Form definition and save this in docs/grammar.md. Update this document as changes are made in the parser.
97- Use PEP8 method and argument names in the pyparsing API ("parse_string", not "parseString")
98- Import pyparsing using "import pyparsing as pp", and use that for all pyparsing references
99  - If referencing anything from pyparsing.common, follow the pyparsing import with "ppc = pp.common" and use ppc as the namespace to access pyparsing.common; same for pyparsing.unicode
100- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution
101- Use results names for robust access to parsed data fields; results names should be valid Python identifiers to support access to values as attributes within the returned ParseResults
102  - Define results names using call format not set_results_name(), ex: full_name = Word(alphas)("first_name") + Word(alphas)("last_name")
103- ParseResults support "in" testing for results names. Use "in" tests for the existence of results names, not hasattr().
104- Use parse actions to do parse-time conversion of data from strings to useful data types
105  - Use objects defined in pyparsing.common for common types like integer, real - these already have their conversion parse actions defined
106- Use the pyparsing ParserElement.run_tests method to run mini validation tests
107
108NOTE: `show_best_practices()` loads the complete guidelines from a Markdown file bundled with the package.
109"""
110# fmt: on
111from typing import NamedTuple
112
113
114class version_info(NamedTuple):
115    major: int
116    minor: int
117    micro: int
118    releaselevel: str
119    serial: int
120
121    @property
122    def __version__(self):
123        return (
124            f"{self.major}.{self.minor}.{self.micro}"
125            + (
126                f"{'r' if self.releaselevel[0] == 'c' else ''}{self.releaselevel[0]}{self.serial}",
127                "",
128            )[self.releaselevel == "final"]
129        )
130
131    def __str__(self):
132        return f"{__name__} {self.__version__} / {__version_time__}"
133
134    def __repr__(self):
135        return f"{__name__}.{type(self).__name__}({', '.join('{}={!r}'.format(*nv) for nv in zip(self._fields, self))})"
136
137
138__version_info__ = version_info(3, 3, 2, "final", 1)
139__version_time__ = "18 Jan 2026 16:35 UTC"
140__version__ = __version_info__.__version__
141__versionTime__ = __version_time__
142__author__ = "Paul McGuire <ptmcg.gm+pyparsing@gmail.com>"
143
144from .warnings import *
145from .util import *
146from .exceptions import *
147from .actions import *
148from .core import __diag__, __compat__
149from .results import *
150from .core import *
151from .core import _builtin_exprs as core_builtin_exprs
152from .helpers import *
153from .helpers import _builtin_exprs as helper_builtin_exprs
154
155from .unicode import unicode_set, UnicodeRangeList, pyparsing_unicode as unicode
156from .testing import pyparsing_test as testing
157from .common import (
158    pyparsing_common as common,
159    _builtin_exprs as common_builtin_exprs,
160)
161from importlib import resources
162import sys
163
164# Compatibility synonyms
165if "pyparsing_unicode" not in globals():
166    pyparsing_unicode = unicode  # type: ignore[misc]
167if "pyparsing_common" not in globals():
168    pyparsing_common = common
169if "pyparsing_test" not in globals():
170    pyparsing_test = testing
171
172core_builtin_exprs += common_builtin_exprs + helper_builtin_exprs
173
174# fmt: off
175_FALLBACK_BEST_PRACTICES = """
176## Planning
177- If not provided or if target language definition is ambiguous, ask for examples of valid strings to be parsed
178- Before developing the pyparsing expressions, define a Backus-Naur Form definition and save this in docs/grammar.md. Update this document as changes are made in the parser.
179
180## Implementing
181- Use PEP8 method and argument names in the pyparsing API ("parse_string", not "parseString")
182- Import pyparsing using "import pyparsing as pp", and use that for all pyparsing references
183  - If referencing anything from pyparsing.common, follow the pyparsing import with "ppc = pp.common" and use ppc as the namespace to access pyparsing.common; same for pyparsing.unicode
184- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution
185- Use results names for robust access to parsed data fields; results names should be valid Python identifiers to support access to values as attributes within the returned ParseResults
186  - Results names should take the place of numeric indexing into parsed results in most places.
187  - Define results names using call format not set_results_name(), ex: full_name = Word(alphas)("first_name") + Word(alphas)("last_name")
188- Use pyparsing Groups to organize sub-expressions
189- If defining the grammar as part of a Parser class, only the finished grammar needs to be implemented as an instance variable
190- ParseResults support "in" testing for results names. Use "in" tests for the existence of results names, not hasattr().
191- Use parse actions to do parse-time conversion of data from strings to useful data types
192  - Use objects defined in pyparsing.common for common types like integer, real - these already have their conversion parse actions defined
193  
194## Testing
195- Use the pyparsing ParserElement.run_tests method to run mini validation tests
196  - You can add comments starting with "#" within the string passed to run_tests to document the individual test cases
197  
198## Debugging
199- If troubleshooting parse actions, use pyparsing's trace_parse_action decorator to echo arguments and return value
200
201(Some best practices may be missing — see the full Markdown file in source at pyparsing/ai/best_practices.md.)
202"""
203# fmt: on
204
205
206def show_best_practices(file=sys.stdout) -> Union[str, None]:
207    """
208    Load and return the project's best practices.
209
210    Example::
211
212        >>> import pyparsing as pp
213        >>> pp.show_best_practices()
214        <!--
215        This file contains instructions for best practices for developing parsers with pyparsing, and can be used by AI agents
216        when generating Python code using pyparsing.
217        -->
218        ...
219
220    This can also be run from the command line::
221
222        python -m pyparsing.ai.show_best_practices
223    """
224    try:
225        path = resources.files(__package__).joinpath("ai/best_practices.md")
226        with path.open("r", encoding="utf-8") as f:
227            content = f.read()
228    except (FileNotFoundError, OSError):
229        content = _FALLBACK_BEST_PRACTICES
230
231    if file is not None:
232        # just print out the content, no need to return it
233        print(content, file=file)
234        return None
235
236    # no output file was specified, return the content as a string
237    return content
238
239
240__all__ = [
241    "__version__",
242    "__version_time__",
243    "__author__",
244    "__compat__",
245    "__diag__",
246    "And",
247    "AtLineStart",
248    "AtStringStart",
249    "CaselessKeyword",
250    "CaselessLiteral",
251    "CharsNotIn",
252    "CloseMatch",
253    "Combine",
254    "DelimitedList",
255    "Dict",
256    "Each",
257    "Empty",
258    "FollowedBy",
259    "Forward",
260    "GoToColumn",
261    "Group",
262    "IndentedBlock",
263    "Keyword",
264    "LineEnd",
265    "LineStart",
266    "Literal",
267    "Located",
268    "PrecededBy",
269    "MatchFirst",
270    "NoMatch",
271    "NotAny",
272    "OneOrMore",
273    "OnlyOnce",
274    "OpAssoc",
275    "Opt",
276    "Optional",
277    "Or",
278    "ParseBaseException",
279    "ParseElementEnhance",
280    "ParseException",
281    "ParseExpression",
282    "ParseFatalException",
283    "ParseResults",
284    "ParseSyntaxException",
285    "ParserElement",
286    "PositionToken",
287    "PyparsingDeprecationWarning",
288    "PyparsingDiagnosticWarning",
289    "PyparsingWarning",
290    "QuotedString",
291    "RecursiveGrammarException",
292    "Regex",
293    "SkipTo",
294    "StringEnd",
295    "StringStart",
296    "Suppress",
297    "Tag",
298    "Token",
299    "TokenConverter",
300    "White",
301    "Word",
302    "WordEnd",
303    "WordStart",
304    "ZeroOrMore",
305    "Char",
306    "alphanums",
307    "alphas",
308    "alphas8bit",
309    "any_close_tag",
310    "any_open_tag",
311    "autoname_elements",
312    "c_style_comment",
313    "col",
314    "common_html_entity",
315    "condition_as_parse_action",
316    "counted_array",
317    "cpp_style_comment",
318    "dbl_quoted_string",
319    "dbl_slash_comment",
320    "delimited_list",
321    "dict_of",
322    "empty",
323    "hexnums",
324    "html_comment",
325    "identchars",
326    "identbodychars",
327    "infix_notation",
328    "java_style_comment",
329    "line",
330    "line_end",
331    "line_start",
332    "lineno",
333    "make_html_tags",
334    "make_xml_tags",
335    "match_only_at_col",
336    "match_previous_expr",
337    "match_previous_literal",
338    "nested_expr",
339    "null_debug_action",
340    "nums",
341    "one_of",
342    "original_text_for",
343    "printables",
344    "punc8bit",
345    "pyparsing_common",
346    "pyparsing_test",
347    "pyparsing_unicode",
348    "python_style_comment",
349    "quoted_string",
350    "remove_quotes",
351    "replace_with",
352    "replace_html_entity",
353    "rest_of_line",
354    "sgl_quoted_string",
355    "show_best_practices",
356    "srange",
357    "string_end",
358    "string_start",
359    "token_map",
360    "trace_parse_action",
361    "ungroup",
362    "unicode_set",
363    "unicode_string",
364    "with_attribute",
365    "with_class",
366    # pre-PEP8 compatibility names
367    "__versionTime__",
368    "anyCloseTag",
369    "anyOpenTag",
370    "cStyleComment",
371    "commonHTMLEntity",
372    "conditionAsParseAction",
373    "countedArray",
374    "cppStyleComment",
375    "dblQuotedString",
376    "dblSlashComment",
377    "delimitedList",
378    "dictOf",
379    "htmlComment",
380    "indentedBlock",
381    "infixNotation",
382    "javaStyleComment",
383    "lineEnd",
384    "lineStart",
385    "locatedExpr",
386    "makeHTMLTags",
387    "makeXMLTags",
388    "matchOnlyAtCol",
389    "matchPreviousExpr",
390    "matchPreviousLiteral",
391    "nestedExpr",
392    "nullDebugAction",
393    "oneOf",
394    "opAssoc",
395    "originalTextFor",
396    "pythonStyleComment",
397    "quotedString",
398    "removeQuotes",
399    "replaceHTMLEntity",
400    "replaceWith",
401    "restOfLine",
402    "sglQuotedString",
403    "stringEnd",
404    "stringStart",
405    "tokenMap",
406    "traceParseAction",
407    "unicodeString",
408    "withAttribute",
409    "withClass",
410    "common",
411    "unicode",
412    "testing",
413]