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, 2, "final", 1)
139__version_time__ = "06 Jan 2026 09:48 UTC"
140__version__ = __version_info__.__version__
141__versionTime__ = __version_time__
142__author__ = "Paul McGuire <ptmcg.gm+pyparsing@gmail.com>"
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
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
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
172core_builtin_exprs += common_builtin_exprs + helper_builtin_exprs
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.
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
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
198## Debugging
199- If troubleshooting parse actions, use pyparsing's trace_parse_action decorator to echo arguments and return value
201(Some best practices may be missing — see the full Markdown file in source at pyparsing/ai/best_practices.md.)
202"""
203# fmt: on
206def show_best_practices(file=sys.stdout) -> Union[str, None]:
207 """
208 Load and return the project's best practices.
210 Example::
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 ...
220 This can also be run from the command line::
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
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
236 # no output file was specified, return the content as a string
237 return content
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]