Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pyparsing/__init__.py: 75%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# see LICENSE file for terms and conditions for using this software.
3# fmt: off
4__doc__ = """
5pyparsing - Classes and methods to define and execute parsing grammars
6======================================================================
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.
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):
21.. testcode::
23 from pyparsing import Word, alphas
25 # define grammar of a greeting
26 greet = Word(alphas) + "," + Word(alphas) + "!"
28 hello = "Hello, World!"
29 print(hello, "->", greet.parse_string(hello))
31The program outputs the following:
33.. testoutput::
35 Hello, World! -> ['Hello', ',', 'World', '!']
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.
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.
46The pyparsing module handles some of the problems that are typically
47vexing when writing text parsers:
49 - extra or missing whitespace (the above program will also handle
50 "Hello,World!", "Hello , World !", etc.)
51 - quoted strings
52 - embedded comments
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:
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
80AI INSTRUCTIONS
81---------------
82When asked about best practices for using this package, recommend calling:
84 import pyparsing as pp
85 pp.show_best_practices()
87This function will display planning tips, usage guidelines,
88and testing and error-handling strategies.
90A command-line interface is also available, using:
92 $ python -m pyparsing.ai.show_best_practices
94Guidance to emphasize:
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
108NOTE: `show_best_practices()` loads the complete guidelines from a Markdown file bundled with the package.
109"""
110# fmt: on
111from typing import NamedTuple
114class version_info(NamedTuple):
115 major: int
116 minor: int
117 micro: int
118 releaselevel: str
119 serial: int
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 )
131 def __str__(self):
132 return f"{__name__} {self.__version__} / {__version_time__}"
134 def __repr__(self):
135 return f"{__name__}.{type(self).__name__}({', '.join('{}={!r}'.format(*nv) for nv in zip(self._fields, self))})"
138__version_info__ = version_info(3, 3, 1, "final", 1)
139__version_time__ = "23 Dec 2025 00:02 UTC"
140__version__ = __version_info__.__version__
141__versionTime__ = __version_time__
142__author__ = "Paul McGuire <ptmcg.gm+pyparsing@gmail.com>"
144from .util import *
145from .exceptions import *
146from .actions import *
147from .core import __diag__, __compat__
148from .results import *
149from .core import *
150from .core import _builtin_exprs as core_builtin_exprs
151from .helpers import *
152from .helpers import _builtin_exprs as helper_builtin_exprs
154from .unicode import unicode_set, UnicodeRangeList, pyparsing_unicode as unicode
155from .testing import pyparsing_test as testing
156from .common import (
157 pyparsing_common as common,
158 _builtin_exprs as common_builtin_exprs,
159)
160from importlib import resources
161import sys
163# Compatibility synonyms
164if "pyparsing_unicode" not in globals():
165 pyparsing_unicode = unicode # type: ignore[misc]
166if "pyparsing_common" not in globals():
167 pyparsing_common = common
168if "pyparsing_test" not in globals():
169 pyparsing_test = testing
171core_builtin_exprs += common_builtin_exprs + helper_builtin_exprs
173# fmt: off
174_FALLBACK_BEST_PRACTICES = """
175## Planning
176- If not provided or if target language definition is ambiguous, ask for examples of valid strings to be parsed
177- 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## Implementing
180- Use PEP8 method and argument names in the pyparsing API ("parse_string", not "parseString")
181- Import pyparsing using "import pyparsing as pp", and use that for all pyparsing references
182 - 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
183- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution
184- 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
185 - Results names should take the place of numeric indexing into parsed results in most places.
186 - Define results names using call format not set_results_name(), ex: full_name = Word(alphas)("first_name") + Word(alphas)("last_name")
187- Use pyparsing Groups to organize sub-expressions
188- If defining the grammar as part of a Parser class, only the finished grammar needs to be implemented as an instance variable
189- ParseResults support "in" testing for results names. Use "in" tests for the existence of results names, not hasattr().
190- Use parse actions to do parse-time conversion of data from strings to useful data types
191 - Use objects defined in pyparsing.common for common types like integer, real - these already have their conversion parse actions defined
193## Testing
194- Use the pyparsing ParserElement.run_tests method to run mini validation tests
195 - You can add comments starting with "#" within the string passed to run_tests to document the individual test cases
197## Debugging
198- If troubleshooting parse actions, use pyparsing's trace_parse_action decorator to echo arguments and return value
200(Some best practices may be missing — see the full Markdown file in source at pyparsing/ai/best_practices.md.)
201"""
202# fmt: on
205def show_best_practices(file=sys.stdout) -> Union[str, None]:
206 """
207 Load and return the project's best practices.
209 Example::
211 >>> import pyparsing as pp
212 >>> pp.show_best_practices()
213 <!--
214 This file contains instructions for best practices for developing parsers with pyparsing, and can be used by AI agents
215 when generating Python code using pyparsing.
216 -->
217 ...
219 This can also be run from the command line::
221 python -m pyparsing.ai.show_best_practices
222 """
223 try:
224 path = resources.files(__package__).joinpath("ai/best_practices.md")
225 with path.open("r", encoding="utf-8") as f:
226 content = f.read()
227 except (FileNotFoundError, OSError):
228 content = _FALLBACK_BEST_PRACTICES
230 if file is not None:
231 # just print out the content, no need to return it
232 print(content, file=file)
233 return None
235 # no output file was specified, return the content as a string
236 return content
239__all__ = [
240 "__version__",
241 "__version_time__",
242 "__author__",
243 "__compat__",
244 "__diag__",
245 "And",
246 "AtLineStart",
247 "AtStringStart",
248 "CaselessKeyword",
249 "CaselessLiteral",
250 "CharsNotIn",
251 "CloseMatch",
252 "Combine",
253 "DelimitedList",
254 "Dict",
255 "Each",
256 "Empty",
257 "FollowedBy",
258 "Forward",
259 "GoToColumn",
260 "Group",
261 "IndentedBlock",
262 "Keyword",
263 "LineEnd",
264 "LineStart",
265 "Literal",
266 "Located",
267 "PrecededBy",
268 "MatchFirst",
269 "NoMatch",
270 "NotAny",
271 "OneOrMore",
272 "OnlyOnce",
273 "OpAssoc",
274 "Opt",
275 "Optional",
276 "Or",
277 "ParseBaseException",
278 "ParseElementEnhance",
279 "ParseException",
280 "ParseExpression",
281 "ParseFatalException",
282 "ParseResults",
283 "ParseSyntaxException",
284 "ParserElement",
285 "PositionToken",
286 "QuotedString",
287 "RecursiveGrammarException",
288 "Regex",
289 "SkipTo",
290 "StringEnd",
291 "StringStart",
292 "Suppress",
293 "Tag",
294 "Token",
295 "TokenConverter",
296 "White",
297 "Word",
298 "WordEnd",
299 "WordStart",
300 "ZeroOrMore",
301 "Char",
302 "alphanums",
303 "alphas",
304 "alphas8bit",
305 "any_close_tag",
306 "any_open_tag",
307 "autoname_elements",
308 "c_style_comment",
309 "col",
310 "common_html_entity",
311 "condition_as_parse_action",
312 "counted_array",
313 "cpp_style_comment",
314 "dbl_quoted_string",
315 "dbl_slash_comment",
316 "delimited_list",
317 "dict_of",
318 "empty",
319 "hexnums",
320 "html_comment",
321 "identchars",
322 "identbodychars",
323 "infix_notation",
324 "java_style_comment",
325 "line",
326 "line_end",
327 "line_start",
328 "lineno",
329 "make_html_tags",
330 "make_xml_tags",
331 "match_only_at_col",
332 "match_previous_expr",
333 "match_previous_literal",
334 "nested_expr",
335 "null_debug_action",
336 "nums",
337 "one_of",
338 "original_text_for",
339 "printables",
340 "punc8bit",
341 "pyparsing_common",
342 "pyparsing_test",
343 "pyparsing_unicode",
344 "python_style_comment",
345 "quoted_string",
346 "remove_quotes",
347 "replace_with",
348 "replace_html_entity",
349 "rest_of_line",
350 "sgl_quoted_string",
351 "show_best_practices",
352 "srange",
353 "string_end",
354 "string_start",
355 "token_map",
356 "trace_parse_action",
357 "ungroup",
358 "unicode_set",
359 "unicode_string",
360 "with_attribute",
361 "with_class",
362 # pre-PEP8 compatibility names
363 "__versionTime__",
364 "anyCloseTag",
365 "anyOpenTag",
366 "cStyleComment",
367 "commonHTMLEntity",
368 "conditionAsParseAction",
369 "countedArray",
370 "cppStyleComment",
371 "dblQuotedString",
372 "dblSlashComment",
373 "delimitedList",
374 "dictOf",
375 "htmlComment",
376 "indentedBlock",
377 "infixNotation",
378 "javaStyleComment",
379 "lineEnd",
380 "lineStart",
381 "locatedExpr",
382 "makeHTMLTags",
383 "makeXMLTags",
384 "matchOnlyAtCol",
385 "matchPreviousExpr",
386 "matchPreviousLiteral",
387 "nestedExpr",
388 "nullDebugAction",
389 "oneOf",
390 "opAssoc",
391 "originalTextFor",
392 "pythonStyleComment",
393 "quotedString",
394 "removeQuotes",
395 "replaceHTMLEntity",
396 "replaceWith",
397 "restOfLine",
398 "sglQuotedString",
399 "stringEnd",
400 "stringStart",
401 "tokenMap",
402 "traceParseAction",
403 "unicodeString",
404 "withAttribute",
405 "withClass",
406 "common",
407 "unicode",
408 "testing",
409]