pynamerx 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pynamer/__init__.py ADDED
@@ -0,0 +1,35 @@
1
+ from __future__ import annotations
2
+
3
+ from .api import RenameResult, RenameStats, process, rename, rename_ast
4
+ from .api import collect_identifiers
5
+ from .config import NameStrategy, RenameConfig
6
+ from .errors import (
7
+ AnalysisError,
8
+ ConfigurationError,
9
+ PynamerError,
10
+ TransformError,
11
+ ValidationError,
12
+ )
13
+ from .mapfile import RenameMap
14
+ from .minify import minify_source
15
+
16
+ __version__ = "0.1.0"
17
+
18
+ __all__ = [
19
+ "__version__",
20
+ "process",
21
+ "rename",
22
+ "rename_ast",
23
+ "collect_identifiers",
24
+ "minify_source",
25
+ "RenameConfig",
26
+ "NameStrategy",
27
+ "RenameMap",
28
+ "RenameResult",
29
+ "RenameStats",
30
+ "PynamerError",
31
+ "ConfigurationError",
32
+ "AnalysisError",
33
+ "TransformError",
34
+ "ValidationError",
35
+ ]
pynamer/__main__.py ADDED
@@ -0,0 +1,127 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ from . import __version__
8
+ from .api import process
9
+ from .config import NameStrategy, RenameConfig
10
+ from .errors import PynamerError
11
+ from .mapfile import RenameMap
12
+
13
+
14
+ def build_parser() -> argparse.ArgumentParser:
15
+ parser = argparse.ArgumentParser(
16
+ prog="pynamer",
17
+ description="Scope-aware Python source renamer / obfuscator.",
18
+ )
19
+ parser.add_argument(
20
+ "source",
21
+ nargs="?",
22
+ help="input .py file (reads stdin when omitted or '-')",
23
+ )
24
+ parser.add_argument("-o", "--output", help="write result here instead of stdout")
25
+ parser.add_argument("--version", action="version", version=f"PyNamer {__version__}")
26
+
27
+ naming = parser.add_argument_group("naming")
28
+ naming.add_argument(
29
+ "--strategy",
30
+ choices=[s.value for s in NameStrategy],
31
+ default=NameStrategy.SEQUENTIAL.value,
32
+ )
33
+ naming.add_argument("--seed", type=int, default=0)
34
+ naming.add_argument("--prefix", default="_0x")
35
+
36
+ passes = parser.add_argument_group("passes")
37
+ passes.add_argument("--no-minify", action="store_true", help="keep readable spacing")
38
+ passes.add_argument("--strip-docstrings", action="store_true")
39
+ passes.add_argument("--builtins", action="store_true", help="alias builtin names")
40
+ passes.add_argument("--hide-init", action="store_true")
41
+ passes.add_argument("--track-instances", action="store_true")
42
+ passes.add_argument("--no-attributes", action="store_true")
43
+ passes.add_argument("--no-kwargs", action="store_true")
44
+
45
+ safety = parser.add_argument_group("safety")
46
+ safety.add_argument(
47
+ "--preserve", nargs="*", default=None, help="names to never rename"
48
+ )
49
+ safety.add_argument(
50
+ "--preserve-attributes", nargs="*", default=None, help="attributes to keep"
51
+ )
52
+ safety.add_argument("--preserve-public", action="store_true")
53
+ safety.add_argument("--no-validate", action="store_true")
54
+
55
+ maps = parser.add_argument_group("maps")
56
+ maps.add_argument("--map-in", help="load a previous rename map (JSON)")
57
+ maps.add_argument("--map-out", help="save the produced rename map (JSON)")
58
+
59
+ parser.add_argument(
60
+ "--stats", action="store_true", help="print a short report to stderr"
61
+ )
62
+ return parser
63
+
64
+
65
+ def _config_from_args(args: argparse.Namespace) -> RenameConfig:
66
+ renaming_map = RenameMap.load(args.map_in) if args.map_in else None
67
+ return RenameConfig(
68
+ strategy=NameStrategy(args.strategy),
69
+ seed=args.seed,
70
+ prefix=args.prefix,
71
+ minify=not args.no_minify,
72
+ strip_docstrings=args.strip_docstrings,
73
+ builtins=args.builtins,
74
+ hide_init=args.hide_init,
75
+ track_instances=args.track_instances,
76
+ rename_attributes=not args.no_attributes,
77
+ rename_kwargs=not args.no_kwargs,
78
+ preserve=frozenset(args.preserve or ()),
79
+ preserve_attributes=frozenset(args.preserve_attributes or ()),
80
+ preserve_public=args.preserve_public,
81
+ validate=not args.no_validate,
82
+ map=renaming_map,
83
+ )
84
+
85
+
86
+ def main(argv: list[str] | None = None) -> int:
87
+ parser = build_parser()
88
+ args = parser.parse_args(argv)
89
+
90
+ if args.source in (None, "-"):
91
+ text = sys.stdin.read()
92
+ filename = "<stdin>"
93
+ else:
94
+ path = Path(args.source)
95
+ if not path.is_file():
96
+ parser.error(f"no such file: {path}")
97
+ text = path.read_text()
98
+ filename = str(path)
99
+
100
+ try:
101
+ result = process(text, filename=filename, config=_config_from_args(args))
102
+ except PynamerError as exc:
103
+ print(f"pynamer: error: {exc}", file=sys.stderr)
104
+ return 1
105
+
106
+ if args.output:
107
+ Path(args.output).write_text(result.source)
108
+ else:
109
+ sys.stdout.write(result.source)
110
+
111
+ if args.map_out:
112
+ result.mapping.save(args.map_out)
113
+
114
+ if args.stats:
115
+ stats = result.stats
116
+ print(
117
+ "pynamer: "
118
+ f"symbols={stats.symbols} attributes={stats.attributes} "
119
+ f"builtins={stats.builtins} "
120
+ f"size={stats.input_size}->{stats.output_size} (-{stats.saved})",
121
+ file=sys.stderr,
122
+ )
123
+ return 0
124
+
125
+
126
+ if __name__ == "__main__":
127
+ raise SystemExit(main())
pynamer/api.py ADDED
@@ -0,0 +1,205 @@
1
+ from __future__ import annotations
2
+
3
+ import ast
4
+ import copy
5
+ from dataclasses import dataclass, field
6
+ from typing import Any, Iterator, Union
7
+
8
+ from .attributes import AttributeAnalyzer
9
+ from .config import NameStrategy, RenameConfig
10
+ from .errors import AnalysisError, ValidationError
11
+ from .mapfile import RenameMap
12
+ from .minify import minify_source
13
+ from .names import NameFactory
14
+ from .renamer import Renamer
15
+ from .symbols import SymbolTable
16
+ from .transforms import apply_hide_init, strip_docstrings
17
+ from .utils import BUILTIN_NAMES, HARD_RESERVED
18
+
19
+ __all__ = [
20
+ "process",
21
+ "rename",
22
+ "rename_ast",
23
+ "collect_identifiers",
24
+ "RenameResult",
25
+ "RenameStats",
26
+ ]
27
+
28
+ Source = Union[str, ast.Module]
29
+
30
+
31
+ @dataclass
32
+ class RenameStats:
33
+
34
+ symbols: int = 0
35
+ attributes: int = 0
36
+ builtins: int = 0
37
+ input_size: int = 0
38
+ output_size: int = 0
39
+
40
+ @property
41
+ def saved(self) -> int:
42
+ return max(0, self.input_size - self.output_size)
43
+
44
+ def as_dict(self) -> dict:
45
+ return {
46
+ "symbols": self.symbols,
47
+ "attributes": self.attributes,
48
+ "builtins": self.builtins,
49
+ "input_size": self.input_size,
50
+ "output_size": self.output_size,
51
+ "saved": self.saved,
52
+ }
53
+
54
+
55
+ @dataclass
56
+ class RenameResult:
57
+
58
+ source: str
59
+ tree: ast.Module
60
+ mapping: RenameMap
61
+ config: RenameConfig
62
+ stats: RenameStats
63
+ plan: Any = field(default=None, repr=False)
64
+
65
+ export = None
66
+
67
+ def __repr__(self) -> str:
68
+ return (
69
+ f"RenameResult(symbols={self.stats.symbols}, "
70
+ f"attributes={self.stats.attributes}, "
71
+ f"size={self.stats.input_size}->{self.stats.output_size})"
72
+ )
73
+
74
+
75
+ def process(
76
+ source: Source,
77
+ *,
78
+ filename: str = "<pynamer>",
79
+ config: RenameConfig | None = None,
80
+ **overrides: Any,
81
+ ) -> RenameResult:
82
+ cfg = _resolve_config(config, overrides)
83
+ if isinstance(source, str):
84
+ text = source
85
+ try:
86
+ tree = ast.parse(text, filename=filename)
87
+ except SyntaxError as exc:
88
+ raise AnalysisError(f"failed to parse {filename}: {exc}") from exc
89
+ elif isinstance(source, ast.Module):
90
+ text = ""
91
+ tree = copy.deepcopy(source)
92
+ else:
93
+ raise TypeError(
94
+ f"source must be str or ast.Module, got {type(source).__name__}"
95
+ )
96
+ return _transform(tree, text, filename, cfg)
97
+
98
+
99
+ def rename(source: Source, **kwargs: Any) -> str:
100
+ return process(source, **kwargs).source
101
+
102
+
103
+ def rename_ast(source: Source, **kwargs: Any) -> ast.Module:
104
+ return process(source, **kwargs).tree
105
+
106
+
107
+ def _resolve_config(
108
+ config: RenameConfig | None, overrides: dict[str, Any]
109
+ ) -> RenameConfig:
110
+ base = config if config is not None else RenameConfig()
111
+ if not isinstance(base, RenameConfig):
112
+ raise TypeError("config must be a RenameConfig instance")
113
+ clean = {k: v for k, v in overrides.items() if v is not None}
114
+ return base.merged(**clean) if clean else base
115
+
116
+
117
+ def _blank_map(cfg: RenameConfig) -> RenameMap:
118
+ return RenameMap(
119
+ strategy=NameStrategy(cfg.strategy).value,
120
+ seed=cfg.seed,
121
+ prefix=cfg.prefix,
122
+ )
123
+
124
+
125
+ def _transform(
126
+ tree: ast.Module, text: str, filename: str, cfg: RenameConfig
127
+ ) -> RenameResult:
128
+ if cfg.strip_docstrings:
129
+ strip_docstrings(tree)
130
+ if cfg.hide_init:
131
+ apply_hide_init(tree)
132
+ ast.fix_missing_locations(tree)
133
+
134
+ table = SymbolTable(tree)
135
+ attributes = AttributeAnalyzer(table, track_instances=cfg.track_instances).run()
136
+
137
+ renaming_map = cfg.map if cfg.map is not None else _blank_map(cfg)
138
+ reserved = set(HARD_RESERVED) | set(BUILTIN_NAMES) | collect_identifiers(tree)
139
+ factory = NameFactory(
140
+ strategy=cfg.strategy,
141
+ seed=cfg.seed,
142
+ prefix=cfg.prefix,
143
+ reserved=reserved,
144
+ )
145
+
146
+ renamer = Renamer(table, attributes, cfg, factory, renaming_map=renaming_map)
147
+ tree = renamer.run(tree)
148
+
149
+ out = ast.unparse(tree)
150
+ out = minify_source(out) if cfg.minify else out.rstrip() + "\n"
151
+
152
+ if cfg.validate:
153
+ try:
154
+ compile(out, filename, "exec")
155
+ except (SyntaxError, ValueError) as exc:
156
+ raise ValidationError(
157
+ f"obfuscated source did not compile: {exc}", source=out
158
+ ) from exc
159
+
160
+ stats = RenameStats(
161
+ symbols=sum(1 for k, v in renaming_map.symbols.items() if k != v),
162
+ attributes=sum(1 for k, v in renaming_map.attributes.items() if k != v),
163
+ builtins=len(renamer.plan.builtin_aliases),
164
+ input_size=len(text),
165
+ output_size=len(out),
166
+ )
167
+ result = RenameResult(out, tree, renaming_map, cfg, stats, plan=renamer.plan)
168
+ result.export = lambda path: renaming_map.save(path)
169
+ return result
170
+
171
+
172
+ def collect_identifiers(tree: ast.AST) -> set[str]:
173
+ names: set[str] = set()
174
+ for node in _iter_nodes(tree):
175
+ if isinstance(node, ast.Name):
176
+ names.add(node.id)
177
+ elif isinstance(node, ast.arg):
178
+ names.add(node.arg)
179
+ elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
180
+ names.add(node.name)
181
+ elif isinstance(node, ast.alias):
182
+ names.add(node.asname or node.name.split(".")[0])
183
+ elif isinstance(node, (ast.Global, ast.Nonlocal)):
184
+ names.update(node.names)
185
+ elif isinstance(node, ast.ExceptHandler) and node.name:
186
+ names.add(node.name)
187
+ elif isinstance(node, (ast.MatchAs, ast.MatchStar)) and node.name:
188
+ names.add(node.name)
189
+ elif isinstance(node, ast.MatchMapping) and node.rest:
190
+ names.add(node.rest)
191
+ elif isinstance(node, ast.keyword) and node.arg:
192
+ names.add(node.arg)
193
+ elif isinstance(node, ast.Attribute):
194
+ names.add(node.attr)
195
+ else:
196
+ tp_name = getattr(node, "name", None)
197
+ if isinstance(tp_name, str) and type(node).__name__.endswith(
198
+ ("TypeVar", "ParamSpec", "TypeVarTuple")
199
+ ):
200
+ names.add(tp_name)
201
+ return names
202
+
203
+
204
+ def _iter_nodes(tree: ast.AST) -> Iterator[ast.AST]:
205
+ yield from ast.walk(tree)
pynamer/attributes.py ADDED
@@ -0,0 +1,170 @@
1
+ from __future__ import annotations
2
+
3
+ import ast
4
+ from dataclasses import dataclass, field
5
+
6
+ from .symbols import ClassInfo, ScopeKind, SymbolTable
7
+ from .utils import attr_is_renamable, target_names
8
+
9
+
10
+ @dataclass
11
+ class AttributeAnalysis:
12
+ internal: set[str] = field(default_factory=set)
13
+ external: set[str] = field(default_factory=set)
14
+ instance_attrs: dict[int, set[str]] = field(default_factory=dict)
15
+ instance_vars: set[str] = field(default_factory=set)
16
+
17
+
18
+ class AttributeAnalyzer:
19
+ def __init__(self, table: SymbolTable, *, track_instances: bool = False) -> None:
20
+ self.table = table
21
+ self.tree = table.tree
22
+ self.track_instances = track_instances
23
+ self.result = AttributeAnalysis()
24
+ self._external: set[str] = set()
25
+ self._defined: set[str] = set()
26
+
27
+ def run(self) -> AttributeAnalysis:
28
+ if self.track_instances:
29
+ self.result.instance_vars = self._collect_instance_vars()
30
+ self._collect_defined_attributes()
31
+ for node in ast.walk(self.tree):
32
+ if isinstance(node, ast.Attribute):
33
+ self._classify(node)
34
+ self.result.external = self._external
35
+ self.result.internal = {
36
+ name
37
+ for name in self._defined
38
+ if attr_is_renamable(name) and name not in self._external
39
+ }
40
+ return self.result
41
+
42
+ def _collect_defined_attributes(self) -> None:
43
+ for info in self.table.classes.values():
44
+ for name, binding in info.scope.names.items():
45
+ if binding.kind == "typeparam":
46
+ continue
47
+ if attr_is_renamable(name):
48
+ self._defined.add(name)
49
+ self.result.instance_attrs[id(info)] = set()
50
+ for node in ast.walk(self.tree):
51
+ if isinstance(node, ast.Attribute) and isinstance(
52
+ node.ctx, (ast.Store, ast.Del)
53
+ ):
54
+ owner = self._self_owner(node)
55
+ if owner is not None:
56
+ self.result.instance_attrs.setdefault(id(owner), set()).add(
57
+ node.attr
58
+ )
59
+ if attr_is_renamable(node.attr):
60
+ self._defined.add(node.attr)
61
+
62
+ def _self_owner(self, node: ast.Attribute) -> ClassInfo | None:
63
+ base = node.value
64
+ if not isinstance(base, ast.Name):
65
+ return None
66
+ scope = self.table.scope_of(node)
67
+ info = self.table.enclosing_class(scope)
68
+ if info is not None and base.id in info.self_params:
69
+ return info
70
+ return None
71
+
72
+ def _classify(self, node: ast.Attribute) -> None:
73
+ if self._is_internal_base(node):
74
+ return
75
+ self._external.add(node.attr)
76
+
77
+ def _is_internal_base(self, node: ast.Attribute) -> bool:
78
+ base = node.value
79
+ scope = self.table.scope_of(node)
80
+
81
+ if isinstance(base, ast.Name):
82
+ info = self.table.enclosing_class(scope)
83
+ if info is not None and base.id in info.self_params:
84
+ return True
85
+ if self.table.class_of_expr(base, scope) is not None:
86
+ return True
87
+ if base.id in self.result.instance_vars:
88
+ return True
89
+ return False
90
+
91
+ if isinstance(base, ast.Call):
92
+ if self._is_super_call(base):
93
+ info = self.table.enclosing_class(scope)
94
+ if info is None:
95
+ return False
96
+ return any(
97
+ node.attr in cls.methods or node.attr in cls.local_attrs()
98
+ for cls in info.mro()[1:]
99
+ )
100
+ if self.table.class_of_expr(base.func, scope) is not None:
101
+ return True
102
+ return False
103
+
104
+ return False
105
+
106
+ @staticmethod
107
+ def _is_super_call(node: ast.Call) -> bool:
108
+ return isinstance(node.func, ast.Name) and node.func.id == "super"
109
+
110
+ def _collect_instance_vars(self) -> set[str]:
111
+ candidates: set[str] = set()
112
+ disqualified: set[str] = set()
113
+
114
+ for node in ast.walk(self.tree):
115
+ if isinstance(node, ast.Assign):
116
+ names = self._assign_targets(node.targets)
117
+ if self._is_local_ctor(node.value, node):
118
+ candidates |= names
119
+ else:
120
+ disqualified |= names
121
+ elif isinstance(node, ast.AnnAssign):
122
+ ok = self._is_local_ctor(node.value, node)
123
+ if not ok:
124
+ ok = isinstance(node.annotation, ast.Name) and (
125
+ self.table.class_of_expr(node.annotation, self._scope(node))
126
+ is not None
127
+ )
128
+ (candidates if ok else disqualified).update(
129
+ target_names(node.target)
130
+ )
131
+ elif isinstance(node, (ast.AugAssign, ast.For, ast.AsyncFor)):
132
+ disqualified |= target_names(node.target)
133
+ elif isinstance(node, ast.comprehension):
134
+ disqualified |= target_names(node.target)
135
+ elif isinstance(node, ast.NamedExpr):
136
+ disqualified |= target_names(node.target)
137
+ elif isinstance(node, ast.withitem) and node.optional_vars is not None:
138
+ disqualified |= target_names(node.optional_vars)
139
+ elif isinstance(node, ast.ExceptHandler) and node.name:
140
+ disqualified.add(node.name)
141
+ elif isinstance(
142
+ node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
143
+ ):
144
+ for arg in (
145
+ list(node.args.posonlyargs)
146
+ + list(node.args.args)
147
+ + list(node.args.kwonlyargs)
148
+ ):
149
+ disqualified.add(arg.arg)
150
+ if node.args.vararg:
151
+ disqualified.add(node.args.vararg.arg)
152
+ if node.args.kwarg:
153
+ disqualified.add(node.args.kwarg.arg)
154
+
155
+ return candidates - disqualified
156
+
157
+ def _scope(self, node: ast.AST):
158
+ return self.table.scope_of(node)
159
+
160
+ def _is_local_ctor(self, value: ast.AST | None, ctx: ast.AST) -> bool:
161
+ if not isinstance(value, ast.Call):
162
+ return False
163
+ return self.table.class_of_expr(value.func, self._scope(ctx)) is not None
164
+
165
+ @staticmethod
166
+ def _assign_targets(targets: list[ast.AST]) -> set[str]:
167
+ names: set[str] = set()
168
+ for target in targets:
169
+ names |= target_names(target)
170
+ return names
pynamer/config.py ADDED
@@ -0,0 +1,88 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass, field, replace
4
+ from enum import Enum
5
+ from typing import TYPE_CHECKING, Any, Iterable
6
+
7
+ from .errors import ConfigurationError
8
+
9
+ if TYPE_CHECKING:
10
+ from .mapfile import RenameMap
11
+
12
+
13
+ class NameStrategy(str, Enum):
14
+
15
+ SEQUENTIAL = "sequential"
16
+ HASH = "hash"
17
+ RANDOM = "random"
18
+ BASE62 = "base62"
19
+ WORDS = "words"
20
+
21
+
22
+ def _as_frozenset(value: Any) -> frozenset[str]:
23
+ if value is None:
24
+ return frozenset()
25
+ if isinstance(value, (str, bytes)):
26
+ raise ConfigurationError("preserve sets must be iterables of names, not a string")
27
+ return frozenset(str(item) for item in value)
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class RenameConfig:
32
+
33
+ strategy: NameStrategy = NameStrategy.SEQUENTIAL
34
+ seed: int = 0
35
+ prefix: str = "_0x"
36
+
37
+ minify: bool = True
38
+ strip_docstrings: bool = False
39
+
40
+ builtins: bool = False
41
+ hide_init: bool = False
42
+ track_instances: bool = False
43
+
44
+ rename_attributes: bool = True
45
+ rename_kwargs: bool = True
46
+
47
+ preserve: frozenset[str] = field(default_factory=frozenset)
48
+ preserve_attributes: frozenset[str] = field(default_factory=frozenset)
49
+ preserve_public: bool = False
50
+ preserve_visit_methods: bool = True
51
+ validate: bool = True
52
+
53
+ map: "RenameMap | None" = None
54
+
55
+ def __post_init__(self) -> None:
56
+ object.__setattr__(self, "preserve", _as_frozenset(self.preserve))
57
+ object.__setattr__(
58
+ self, "preserve_attributes", _as_frozenset(self.preserve_attributes)
59
+ )
60
+ if not isinstance(self.strategy, NameStrategy):
61
+ try:
62
+ object.__setattr__(self, "strategy", NameStrategy(self.strategy))
63
+ except ValueError as exc:
64
+ raise ConfigurationError(f"unknown strategy {self.strategy!r}") from exc
65
+ if self.prefix and not _valid_prefix(self.prefix):
66
+ raise ConfigurationError(
67
+ f"prefix {self.prefix!r} cannot start a Python identifier"
68
+ )
69
+
70
+ def merged(self, **overrides: Any) -> "RenameConfig":
71
+ clean = {k: v for k, v in overrides.items() if v is not None}
72
+ if not clean:
73
+ return self
74
+ unknown = set(clean) - set(self.__dataclass_fields__)
75
+ if unknown:
76
+ raise ConfigurationError(
77
+ "unknown configuration option(s): " + ", ".join(sorted(unknown))
78
+ )
79
+ clean["preserve"] = _as_frozenset(clean.get("preserve", self.preserve))
80
+ clean["preserve_attributes"] = _as_frozenset(
81
+ clean.get("preserve_attributes", self.preserve_attributes)
82
+ )
83
+ return replace(self, **clean)
84
+
85
+
86
+ def _valid_prefix(prefix: str) -> bool:
87
+ first = prefix[0]
88
+ return first == "_" or first.isalpha()
pynamer/errors.py ADDED
@@ -0,0 +1,24 @@
1
+ from __future__ import annotations
2
+
3
+
4
+ class PynamerError(Exception):
5
+ pass
6
+
7
+
8
+ class ConfigurationError(PynamerError, ValueError):
9
+ pass
10
+
11
+
12
+ class AnalysisError(PynamerError):
13
+ pass
14
+
15
+
16
+ class TransformError(PynamerError):
17
+ pass
18
+
19
+
20
+ class ValidationError(TransformError):
21
+
22
+ def __init__(self, message: str, *, source: str | None = None) -> None:
23
+ super().__init__(message)
24
+ self.source = source