Use blib2to3 parser from black package to support match statement

docspec-python/.changelog/_unreleased.toml

@@ -0,0 +1,21 @@
+# NOTE (@nrser) Obviously these files have some format/structure to them but
+#   I'm not familiar with it and I'm not sure where to find it documented;
+#   please forgive any mistakes.
+
+# Guessing this would not be set in an "unreleased" entry, but anyways today's
+# date is thrown in there
+# 
+# release-date = "2023-02-28"
+
+[[entries]]
+# Guessing this is just a uuid, I generated one with `uuidgen`
+id = "58c1a773-c483-4014-8238-80d9f65f7b57"
+# I guess this is a 'fix'? Python version for `docspec-python` is not restricted
+# above, so I assume it is supposed to work for Python 3.10+ with `match`
+type = "fix"
+description = """\
+  Swap in `blib2to3` parser (bundled with `black` package) for the stdlib \
+  `lib2to3` module in order to support `match` statement (PEP 634 – Structural \
+  Pattern Matching). \
+"""
+author = "@nrser"

docspec-python/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "docspec-python"
-version = "2.0.2"
+version = "2.0.2+blib2to3"
 description = "A parser based on lib2to3 producing docspec data from Python source code."
 authors = ["Niklas Rosenstein <[email protected]>"]
 license = "MIT"
@@ -12,6 +12,7 @@ packages = [{ include = "docspec_python", from="src" }]
 python = "^3.7"
 docspec = "^2.0.2"
 "nr.util" = ">=0.7.0"
+black = "^23.1.0"
 
 [tool.poetry.dev-dependencies]
 mypy = "*"

docspec-python/src/docspec_python/__init__.py

@@ -46,10 +46,10 @@
 
 
 def load_python_modules(
-  modules: t.Sequence[str] = None,
-  packages: t.Sequence[str] = None,
-  search_path: t.Sequence[t.Union[str, Path]] = None,
-  options: ParserOptions = None,
+  modules: t.Optional[t.Sequence[str]] = None,
+  packages: t.Optional[t.Sequence[str]] = None,
+  search_path: t.Optional[t.Sequence[t.Union[str, Path]]] = None,
+  options: t.Optional[ParserOptions] = None,
   raise_: bool = True,
   encoding: t.Optional[str] = None,
 ) -> t.Iterable[Module]:
@@ -133,7 +133,7 @@ def parse_python_module(  # type: ignore
   return parser.parse(ast, filename, module_name)
 
 
-def find_module(module_name: str, search_path: t.Sequence[t.Union[str, Path]] = None) -> str:
+def find_module(module_name: str, search_path: t.Optional[t.Sequence[t.Union[str, Path]]] = None) -> str:
   """ Finds the filename of a module that can be parsed with #parse_python_module(). If *search_path* is not set,
   the default #sys.path is used to search for the module. If *module_name* is a Python package, it will return the
   path to the package's `__init__.py` file. If the module does not exist, an #ImportError is raised. This is also
@@ -165,7 +165,7 @@ def find_module(module_name: str, search_path: t.Sequence[t.Union[str, Path]] =
 
 def iter_package_files(
   package_name: str,
-  search_path: t.Sequence[t.Union[str, Path]] = None,
+  search_path: t.Optional[t.Sequence[t.Union[str, Path]]] = None,
 ) -> t.Iterable[t.Tuple[str, str]]:
   """ Returns an iterator for the Python source files in the specified package. The items returned
   by the iterator are tuples of the module name and filename. Supports a PEP 420 namespace package