markwork 0.1.0.dev0__py3-none-any.whl

markwork/engine/_nested_bound.py

@@ -0,0 +1,53 @@
+"""
+The 'nestedBound' function collects names bound inside a nested scope.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import ast
+
+_SCOPE_NODES = (
+  ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef,
+  ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp,
+)
+
+
+def nestedBound(tree: ast.AST) -> set:
+  """Return the names bound inside a nested scope rather than at module
+  scope.
+
+  A nested scope is a function, lambda, comprehension or class body. A
+  module-level name that also turns up here is shadowed somewhere in the
+  file, so its uses are left unlinked rather than risk pointing at the
+  wrong line.
+
+  Parameters
+  ----------
+  tree : ast.AST
+      The parsed module.
+
+  Returns
+  -------
+  set of str
+      Every name bound in a nested scope.
+  """
+  names = set()
+
+  def walk(node: ast.AST, nested: bool) -> None:
+    for child in ast.iter_child_nodes(node):
+      if nested:
+        if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store):
+          names.add(child.id)
+        elif isinstance(child, ast.arg):
+          names.add(child.arg)
+        elif isinstance(
+            child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+          names.add(child.name)
+        elif isinstance(child, (ast.Import, ast.ImportFrom)):
+          for alias in child.names:
+            names.add(alias.asname or alias.name.split(".")[0])
+      walk(child, nested or isinstance(child, _SCOPE_NODES))
+
+  walk(tree, False)
+  return names

markwork/engine/_parse_init.py

@@ -0,0 +1,52 @@
+"""
+The 'parseInit' function reads a package __init__.py into its public
+re-export mapping.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import ast
+from pathlib import Path
+
+
+def parseInit(initPath: Path):
+  """Read a package __init__.py into its public names and their sources.
+
+  Two relative import shapes are understood: 'from . import submodule'
+  binds a public name to a child, and 'from .module import Name' binds it
+  to a documented symbol. Non-constant __all__ entries and absolute
+  imports are passed over.
+
+  Parameters
+  ----------
+  initPath : Path
+      The __init__.py to read and parse.
+
+  Returns
+  -------
+  tuple
+      A pair '(allNames, sourceMap)'. 'allNames' is the list of public
+      names in __all__. 'sourceMap' maps a public name to either
+      '("child", childName)' or '("from", module, origName)'.
+  """
+  tree = ast.parse(initPath.read_text(encoding="utf-8"))
+  allNames = []
+  sourceMap = {}
+  for node in tree.body:
+    if isinstance(node, ast.Assign):
+      isAll = any(
+          isinstance(t, ast.Name) and t.id == "__all__"
+          for t in node.targets
+      )
+      if isAll and isinstance(node.value, (ast.List, ast.Tuple)):
+        allNames = [e.value for e in node.value.elts
+                    if isinstance(e, ast.Constant)]
+    elif isinstance(node, ast.ImportFrom) and node.level >= 1:
+      if node.module is None:
+        for alias in node.names:
+          sourceMap[alias.asname or alias.name] = ("child", alias.name)
+      else:
+        for alias in node.names:
+          key = alias.asname or alias.name
+          sourceMap[key] = ("from", node.module, alias.name)
+  return allNames, sourceMap

markwork/engine/_pydocs.py

@@ -0,0 +1,10 @@
+"""
+The 'PYDOCS' constant is the base URL of the Python documentation that
+every standard-library and builtin link is built against.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+#  Pinned to the '3' series so the anchor tables in '_builtin_links' stay
+#  valid. The live-anchor test guards against drift on this version.
+PYDOCS = "https://docs.python.org/3/"