funcsnap 0.0.1.dev1__py3-none-any.whl

funcsnap/__init__.py

@@ -0,0 +1,12 @@
+"""Extract and reconstruct Python function source and dependencies."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from funcsnap.save_source_function import get_source_functions, reconstruct
+
+__all__ = ["__version__", "get_source_functions", "reconstruct"]
+
+try:
+    __version__ = version("funcsnap")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

funcsnap/save_source_function.py

@@ -0,0 +1,507 @@
+"""Module for analyzing functions and extracting their dependencies."""
+
+import ast
+import inspect
+import os
+import re
+import site
+import sysconfig
+import textwrap
+from typing import Any
+
+
+def _get_env_dirs() -> list[str]:
+    """Return absolute paths of Python environment directories."""
+    dirs: set[str] = set()
+    for path in sysconfig.get_paths().values():
+        if path:
+            dirs.add(os.path.abspath(path))
+    try:
+        for path in site.getsitepackages():
+            dirs.add(os.path.abspath(path))
+    except AttributeError:
+        pass
+    try:
+        dirs.add(os.path.abspath(site.getusersitepackages()))
+    except AttributeError:
+        pass
+    return list(dirs)
+
+
+_ENV_DIRS: list[str] = _get_env_dirs()
+
+
+def _is_under(path: str, directory: str) -> bool:
+    """Return True if path is inside directory."""
+    return path == directory or path.startswith(directory + os.sep)
+
+
+class FunctionAnalyzer:
+    """
+    Analyzes a function and extracts all used functions,
+    variables, classes, and modules.
+    """
+
+    def __init__(
+        self,
+        exclude_dirs: list[str] | None = None,
+        include_dirs: list[str] | None = None,
+    ):
+        self.results: dict[str, dict[str, Any]] = {}
+        self.visited: set[str] = set()
+        self._exclude_dirs = [os.path.abspath(d) for d in (exclude_dirs or [])]
+        self._include_dirs = (
+            [os.path.abspath(d) for d in include_dirs]
+            if include_dirs is not None
+            else None
+        )
+
+    def _should_analyze(self, file_path: str) -> bool:
+        """Return True if we should recurse into this file."""
+        if not file_path or file_path == "unknown":
+            return False
+        abs_path = os.path.abspath(file_path)
+        for env_dir in _ENV_DIRS:
+            if _is_under(abs_path, env_dir):
+                return False
+        for excl_dir in self._exclude_dirs:
+            if _is_under(abs_path, excl_dir):
+                return False
+        if self._include_dirs is not None:
+            return any(_is_under(abs_path, d) for d in self._include_dirs)
+        return True
+
+    def analyze_function(self, func) -> dict[str, dict[str, Any]]:
+        """Analyze a function and return a dictionary of all used symbols."""
+        self.results = {}
+        self.visited = set()
+        self._analyze_func(func)
+        return self.results
+
+    def _analyze_func(self, func):
+        """Recursively analyze a function and its dependencies."""
+        if not (inspect.isfunction(func) or inspect.ismethod(func)):
+            return
+        func_id = self._get_func_id(func)
+        if func_id in self.visited:
+            return
+        self.visited.add(func_id)
+
+        file_path = self._get_file(func)
+        source = self._get_source(func)
+        used_names = self._get_used_names(source)
+        globals_dict = (
+            func.__globals__ if inspect.isfunction(func) else func.__func__.__globals__
+        )
+
+        self.results[func_id] = {
+            "value": source,
+            "type": "function",
+            "file": file_path,
+            "external_vars": [],
+            "imports": self._extract_needed_imports(file_path, used_names),
+        }
+        self.results[func_id]["external_vars"] = self._collect_deps(
+            used_names, globals_dict, func.__module__, source
+        )
+
+    def _collect_deps(
+        self,
+        used_names: set[str],
+        globals_dict: dict,
+        module_name: str,
+        source: str = "",
+    ) -> list[str]:
+        """Process used names, populate results, and return dep ID list."""
+        dep_ids: list[str] = []
+        seen: set[str] = set()
+
+        for name in used_names:
+            if name not in globals_dict:
+                continue
+            value = globals_dict[name]
+
+            if inspect.isfunction(value):
+                dep_id = self._get_func_id(value)
+                if dep_id not in seen:
+                    seen.add(dep_id)
+                    dep_ids.append(dep_id)
+                if self._should_analyze(self._get_file(value)):
+                    self._analyze_func(value)
+
+            elif inspect.isclass(value):
+                dep_id = self._get_class_id(value)
+                if dep_id not in seen:
+                    seen.add(dep_id)
+                    dep_ids.append(dep_id)
+                if dep_id not in self.results and self._should_analyze(
+                    self._get_file(value)
+                ):
+                    self._analyze_class(value)
+
+            elif inspect.ismodule(value):
+                mod_id = value.__name__
+                if mod_id not in seen:
+                    seen.add(mod_id)
+                    dep_ids.append(mod_id)
+                # Resolve `name.attr` accesses (e.g. `prim.clamp`) and recurse
+                # into whatever they resolve to in the module.
+                if source:
+                    for attr in _attr_accesses(source, name):
+                        attr_val = getattr(value, attr, None)
+                        if attr_val is None:
+                            continue
+                        if inspect.isfunction(attr_val):
+                            sub_id = self._get_func_id(attr_val)
+                            if sub_id not in seen:
+                                seen.add(sub_id)
+                                dep_ids.append(sub_id)
+                            if self._should_analyze(self._get_file(attr_val)):
+                                self._analyze_func(attr_val)
+                        elif inspect.isclass(attr_val):
+                            sub_id = self._get_class_id(attr_val)
+                            if sub_id not in seen:
+                                seen.add(sub_id)
+                                dep_ids.append(sub_id)
+                            if sub_id not in self.results and self._should_analyze(
+                                self._get_file(attr_val)
+                            ):
+                                self._analyze_class(attr_val)
+
+            else:
+                var_id = f"{module_name}.{name}"
+                if var_id not in self.results:
+                    self.results[var_id] = {
+                        "type": "variable",
+                        "value": repr(value),
+                    }
+                if var_id not in seen:
+                    seen.add(var_id)
+                    dep_ids.append(var_id)
+
+        return dep_ids
+
+    def _analyze_class(self, cls):
+        """Add a class to results and collect method dependencies."""
+        cls_id = self._get_class_id(cls)
+        cls_file = self._get_file(cls)
+        cls_source = self._get_source(cls)
+        cls_used = self._get_used_names(cls_source)
+
+        # Set entry before recursing to prevent re-entry
+        self.results[cls_id] = {
+            "value": cls_source,
+            "type": "class",
+            "file": cls_file,
+            "external_vars": [],
+            "imports": self._extract_needed_imports(cls_file, cls_used),
+        }
+
+        if not self._should_analyze(cls_file):
+            return
+
+        # Collect deps from all methods without adding methods as separate entries
+        all_dep_ids: list[str] = []
+        seen_deps: set[str] = set()
+        for _, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+            method_source = self._get_source(method)
+            method_used = self._get_used_names(method_source)
+            for dep_id in self._collect_deps(
+                method_used, method.__globals__, method.__module__, method_source
+            ):
+                if dep_id not in seen_deps:
+                    seen_deps.add(dep_id)
+                    all_dep_ids.append(dep_id)
+
+        self.results[cls_id]["external_vars"] = all_dep_ids
+
+    def _extract_needed_imports(
+        self, file_path: str, used_names: set[str]
+    ) -> list[str]:
+        """Extract top-level imports from file whose bound names appear in used_names"""
+        if not file_path or file_path == "unknown":
+            return []
+        try:
+            source = open(file_path).read()
+            tree = ast.parse(source)
+        except Exception:
+            return []
+
+        imports: list[str] = []
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.Import):
+                bound = [alias.asname or alias.name for alias in node.names]
+                if any(n in used_names for n in bound):
+                    text = ast.get_source_segment(source, node)
+                    if text:
+                        imports.append(text.strip())
+            elif isinstance(node, ast.ImportFrom):
+                bound = [alias.asname or alias.name for alias in node.names]
+                if any(n in used_names for n in bound):
+                    text = ast.get_source_segment(source, node)
+                    if text:
+                        imports.append(text.strip())
+        return imports
+
+    def _get_func_id(self, func) -> str:
+        return f"{func.__module__}.{func.__name__}"
+
+    def _get_class_id(self, cls) -> str:
+        return f"{cls.__module__}.{cls.__name__}"
+
+    def _get_source(self, obj) -> str:
+        try:
+            return inspect.getsource(obj)
+        except Exception:
+            return ""
+
+    def _get_file(self, obj) -> str:
+        try:
+            return inspect.getfile(obj)
+        except Exception:
+            return "unknown"
+
+    def _get_used_names(self, source: str) -> set[str]:
+        """Parse AST and collect all referenced names in the source."""
+        used: set[str] = set()
+        try:
+            tree = ast.parse(textwrap.dedent(source))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+                    used.add(node.id)
+                elif isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Load):
+                    base = node
+                    while isinstance(base, ast.Attribute):
+                        base = base.value
+                    if isinstance(base, ast.Name):
+                        used.add(base.id)
+        except Exception:
+            pass
+        return used
+
+
+def get_source_functions(
+    func,
+    exclude_dirs: list[str] | None = None,
+    include_dirs: list[str] | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Analyze a function and return a dictionary of all used symbols."""
+    analyzer = FunctionAnalyzer(exclude_dirs=exclude_dirs, include_dirs=include_dirs)
+    return analyzer.analyze_function(func)
+
+
+def _import_bound_names(import_line: str) -> set[str]:
+    """Return the set of names bound by an import statement string."""
+    try:
+        tree = ast.parse(import_line)
+    except SyntaxError:
+        return set()
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                names.add(alias.asname or alias.name.split(".")[0])
+    return names
+
+
+def _is_relative_import(import_line: str) -> bool:
+    """Return True if the import line is a relative (intra-package) import."""
+    try:
+        tree = ast.parse(import_line)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.level > 0:
+                return True
+    except SyntaxError:
+        pass
+    return False
+
+
+def _attr_accesses(source: str, name: str) -> set[str]:
+    """
+    Return attribute names accessed on `name` in source
+    (e.g. prim.clamp → {'clamp'}).
+
+    """
+    attrs: set[str] = set()
+    try:
+        tree = ast.parse(textwrap.dedent(source))
+        for node in ast.walk(tree):
+            if (
+                isinstance(node, ast.Attribute)
+                and isinstance(node.value, ast.Name)
+                and node.value.id == name
+            ):
+                attrs.add(node.attr)
+    except Exception:
+        pass
+    return attrs
+
+
+def _module_slug(full_key: str) -> str:
+    """'mylib.core.primitives.scale' → 'mylib_core_primitives'."""
+    return full_key.rsplit(".", 1)[0].replace(".", "_")
+
+
+def _prefixed_name(full_key: str) -> str:
+    """'mylib.core.primitives.scale' → '_mylib_core_primitives__scale'."""
+    return f"_{_module_slug(full_key)}__{full_key.rsplit('.', 1)[-1]}"
+
+
+def reconstruct(results: dict[str, dict[str, Any]]) -> str:
+    """Produce a single executable Python string from get_source_functions() output."""
+    # 1. Separate variables from functions/classes
+    variables = {k: v for k, v in results.items() if v.get("type") == "variable"}
+    definitions = {
+        k: v for k, v in results.items() if v.get("type") in ("function", "class")
+    }
+
+    # 2. Detect name collisions: multiple result keys sharing the same short name
+    name_to_keys: dict[str, list[str]] = {}
+    for key in definitions:
+        name_to_keys.setdefault(key.split(".")[-1], []).append(key)
+    colliding_names: set[str] = {n for n, ks in name_to_keys.items() if len(ks) > 1}
+
+    # Map every key to the name it will be emitted under
+    key_to_emitted: dict[str, str] = {
+        key: (
+            _prefixed_name(key)
+            if key.split(".")[-1] in colliding_names
+            else key.split(".")[-1]
+        )
+        for key in definitions
+    }
+
+    # The set of names that will be visible at module level after emit
+    defined_names: set[str] = set(key_to_emitted.values()) | set(colliding_names)
+
+    # All definition source texts — used to scan for module attribute accesses
+    def_sources: list[str] = [v["value"] for v in definitions.values()]
+
+    # 3. Classify import lines
+    all_imports: list[str] = []
+    module_alias_shims: dict[str, set[str]] = {}  # alias → attr names to expose
+    seen_imports: set[str] = set()
+
+    for entry in results.values():
+        for imp in entry.get("imports", []):
+            if imp in seen_imports:
+                continue
+            seen_imports.add(imp)
+            bound = _import_bound_names(imp)
+            # Drop if every bound name will be defined in the output
+            if bound and bound.issubset(defined_names):
+                continue
+            # Relative imports can't be resolved in an exec() context
+            if _is_relative_import(imp):
+                for alias in bound:
+                    if alias not in defined_names and alias not in module_alias_shims:
+                        attrs_used: set[str] = set()
+                        for src in def_sources:
+                            attrs_used |= _attr_accesses(src, alias)
+                        known = attrs_used & defined_names
+                        if known:
+                            module_alias_shims[alias] = known
+                continue  # never emit relative imports verbatim
+            all_imports.append(imp)
+
+    # 4. Topological sort: dependencies before dependents (Kahn's algorithm)
+    def_keys = set(definitions.keys())
+    in_degree = {k: 0 for k in def_keys}
+    successors: dict[str, list[str]] = {k: [] for k in def_keys}
+
+    for key, entry in definitions.items():
+        for dep in entry.get("external_vars", []):
+            if dep in def_keys:
+                in_degree[key] += 1
+                successors[dep].append(key)
+
+    queue = sorted(k for k in def_keys if in_degree[k] == 0)
+    sorted_defs: list[str] = []
+    while queue:
+        node = queue.pop(0)
+        sorted_defs.append(node)
+        for succ in sorted(successors[node]):
+            in_degree[succ] -= 1
+            if in_degree[succ] == 0:
+                queue.append(succ)
+                queue.sort()
+
+    # Append any remaining (cycle fallback)
+    sorted_defs.extend(sorted(k for k in def_keys if k not in sorted_defs))
+
+    # 5. Build output string
+    parts: list[str] = []
+
+    if all_imports or module_alias_shims:
+        parts.append("# --- Imports ---")
+        if module_alias_shims:
+            parts.append("import types")
+        parts.extend(all_imports)
+        parts.append("")
+
+    if variables:
+        parts.append("# --- Variables ---")
+        for key, entry in variables.items():
+            var_name = key.split(".")[-1]
+            parts.append(f"{var_name} = {entry['value']}")
+        parts.append("")
+
+    if sorted_defs:
+        parts.append("# --- Definitions ---")
+        for key in sorted_defs:
+            source = textwrap.dedent(definitions[key]["value"]).strip()
+            emitted = key_to_emitted[key]
+            orig = key.split(".")[-1]
+            if emitted != orig:
+                # Rename the first def/class line to the prefixed name
+                source = re.sub(
+                    rf"^((?:async\s+)?def|class)\s+{re.escape(orig)}\b",
+                    rf"\1 {emitted}",
+                    source,
+                    count=1,
+                )
+            parts.append(source)
+            parts.append("")
+
+    # SimpleNamespace shims for module aliases
+    # (e.g. `prim = types.SimpleNamespace(clamp=clamp)`)
+    # Emitted after definitions because they reference already-defined names.
+    if module_alias_shims:
+        parts.append("# --- Module shims ---")
+        for alias in sorted(module_alias_shims):
+            attrs = sorted(module_alias_shims[alias])
+            # Attrs may themselves have been prefixed due to collision;
+            # use key_to_emitted by looking up
+            # the short attr name in the emitted names map
+            resolved_attrs = []
+            for a in attrs:
+                # Find what name 'a' is actually emitted as
+                emitted_a = next(
+                    (key_to_emitted[k] for k in definitions if k.split(".")[-1] == a),
+                    a,
+                )
+                resolved_attrs.append(f"{a}={emitted_a}")
+            attr_str = ", ".join(resolved_attrs)
+            parts.append(f"{alias} = types.SimpleNamespace({attr_str})")
+        parts.append("")
+
+    # 6. Collision aliases — emit after all defs and shims
+    if colliding_names:
+        parts.append("# --- Collision aliases ---")
+        for short_name in sorted(colliding_names):
+            ordered_keys = [k for k in sorted_defs if k.split(".")[-1] == short_name]
+            if not ordered_keys:
+                continue
+            canonical = ordered_keys[0]
+            canonical_mod = canonical.rsplit(".", 1)[0]
+            parts.append(
+                f"# '{short_name}': {len(ordered_keys)} versions — "
+                f"canonical from {canonical_mod}"
+            )
+            parts.append(f"{short_name} = {key_to_emitted[canonical]}")
+            for k in ordered_keys[1:]:
+                slug = _module_slug(k)
+                parts.append(f"{short_name}__{slug} = {key_to_emitted[k]}")
+        parts.append("")
+
+    return "\n".join(parts)

funcsnap-0.0.1.dev1.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: funcsnap
+Version: 0.0.1.dev1
+Summary: Analyze Python functions and extract dependency source for reconstruction
+Project-URL: Repository, https://github.com/yourusername/funcsnap
+Author: funcsnap contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ast,introspection,serialization,source
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: numpy>=1.26; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# funcsnap
+
+Analyze Python functions, walk their dependencies, and **reconstruct** a self-contained source string suitable for `exec()`.
+
+## Install
+
+```bash
+pip install funcsnap
+```
+
+## Development
+
+Clone the repo, create a virtual environment, then:
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+Version strings are derived from Git tags ([hatch-vcs](https://github.com/ofek/hatch-vcs)). Without a repository or tags, builds use the fallback version from `pyproject.toml`.
+
+### PyPI releases (maintainers)
+
+1. Configure **trusted publishing** on [PyPI](https://pypi.org/manage/account/publishing/) for this repository and workflow `.github/workflows/publish.yml` (optional GitHub Environment `pypi`).
+2. Merge your changes to `main`, then tag and push: `git tag v0.1.0 && git push origin v0.1.0` (use the next semantic version). The publish workflow runs on tags matching `v*`.
+
+Update the `Repository` URL in `pyproject.toml` under `[project.urls]` to match your GitHub repo.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

funcsnap-0.0.1.dev1.dist-info/RECORD

@@ -0,0 +1,6 @@
+funcsnap/__init__.py,sha256=ZiA7jSDJBK7H96rON6OOwffu6ncjtdY94NGmtPS6RHQ,375
+funcsnap/save_source_function.py,sha256=-AYNwXxdnzwc_rO-Wr4JA7J5roYuZg5uDQWAoql9N4A,18702
+funcsnap-0.0.1.dev1.dist-info/METADATA,sha256=FhwhmcpogNy-Oa3M6q5YKo93TzIEWyBQ1nA4YfRBiBY,2077
+funcsnap-0.0.1.dev1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+funcsnap-0.0.1.dev1.dist-info/licenses/LICENSE,sha256=-kRiz8ytzAGxYnzf5Uofpesw6lmHfjhtChFHmYTfz10,1078
+funcsnap-0.0.1.dev1.dist-info/RECORD,,

funcsnap-0.0.1.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

funcsnap-0.0.1.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 funcsnap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.