samarth 0.2.0__tar.gz

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.
samarth-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,242 @@
1
+ Metadata-Version: 2.4
2
+ Name: samarth
3
+ Version: 0.2.0
4
+ Summary: Multi-platform Python protection pipeline — PyArmor, Nuitka, and pure-Python modes
5
+ Author-email: Samarth <creatorpc@proton.me>
6
+ License: MIT
7
+ Classifier: Programming Language :: Python :: 3.10
8
+ Classifier: Programming Language :: Python :: 3.11
9
+ Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Programming Language :: Python :: 3.13
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Topic :: Software Development :: Build Tools
13
+ Requires-Python: <3.14,>=3.10
14
+ Description-Content-Type: text/markdown
15
+ Requires-Dist: pyarmor>=9.0
16
+ Requires-Dist: nuitka>=2.0
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest; extra == "dev"
19
+
20
+ # SAMARTH ENC
21
+
22
+ A Python build tool that chains multiple protection strategies — PyArmor
23
+ bytecode encryption, Nuitka native compilation, or both — into one command.
24
+ It auto-detects your environment and picks the strongest strategy that
25
+ actually works there, rather than silently producing output that won't run.
26
+
27
+ ## Platform support
28
+
29
+ | Platform | Universal | PyArmor | Nuitka | Combined |
30
+ |---|---|---|---|---|
31
+ | Linux x86_64 | ✓ | ✓ | ✓ | ✓ |
32
+ | Linux ARM64 | ✓ | ✓ | ✓ | ✓ |
33
+ | Windows x86_64 | ✓ | ✓ | ✓ | ✓ |
34
+ | macOS x86_64/ARM64 | ✓ | ✓ | ✓ | ✓ |
35
+ | Termux (ARM64) | ✓ | ✓ (linux.aarch64) | ✓ (module only, Nuitka 2.6.7+) | ✗ |
36
+ | Pydroid 3 | ✓ | Experimental | ✗ | ✗ |
37
+
38
+ **Notes:**
39
+ - Nuitka standalone/onefile builds don't work reliably on Termux due to
40
+ Android's dynamic linker not matching standard Linux assumptions.
41
+ - Pydroid has no accessible C compiler. PyArmor works experimentally there
42
+ (its Android runtime is built for Termux/NDK Python, not Pydroid's own
43
+ build — test before shipping).
44
+ - Cross-compiled artifacts are never portable. Build on the target device or
45
+ use PyArmor's `--platform` flag for cross-compilation.
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ pip install samarth
51
+ ```
52
+
53
+ If you want PyArmor and/or Nuitka protection (not just Universal mode):
54
+
55
+ ```bash
56
+ pip install pyarmor nuitka
57
+ ```
58
+
59
+ Nuitka requires a C compiler:
60
+
61
+ ```bash
62
+ # Debian/Ubuntu/VPS
63
+ sudo apt install build-essential patchelf
64
+
65
+ # Termux
66
+ pkg install clang patchelf
67
+
68
+ # Windows — Nuitka will offer to download MinGW64 on first run
69
+ # macOS
70
+ xcode-select --install
71
+ ```
72
+
73
+ **Termux-specific PyArmor fix** (if you get a `.so` load error):
74
+
75
+ ```bash
76
+ patchelf --add-needed libpython3.11.so.0.1 \
77
+ $(python -c "import pyarmor; print(__import__('pathlib').Path(pyarmor.__file__).parent)")/cli/core/android/aarch64/pytransform3.so
78
+ ```
79
+
80
+ Replace `3.11` with your actual Python version.
81
+
82
+ ## Usage
83
+
84
+ ### Interactive menu
85
+
86
+ ```
87
+ samarth
88
+ ```
89
+
90
+ ```
91
+ SAMARTH ENC
92
+
93
+ [1] Universal Python Build
94
+ [2] PyArmor Protection
95
+ [3] Native Compilation
96
+ [4] PyArmor + Nuitka
97
+ [5] Termux Build
98
+ [6] Pydroid Compatibility Build
99
+ [7] Automatic Platform Detection
100
+ [8] Compatibility Checker
101
+ [9] Dependency Checker
102
+ [10] Integrity Checker
103
+ [11] Debug Protected File
104
+ [12] Build Diagnostics
105
+ [0] Exit
106
+ ```
107
+
108
+ ### CLI subcommands
109
+
110
+ ```bash
111
+ samarth build app.py # auto-select best mode
112
+ samarth build app.py --mode pyarmor # specific mode
113
+ samarth build mypackage/ --mode combined --output dist/
114
+
115
+ samarth detect # show OS/arch/tool report
116
+ samarth check # show which modes work here
117
+ samarth deps # check tool availability
118
+
119
+ samarth integrity app.py <sha256-hash> # verify file hasn't changed
120
+ samarth debug dist/app.py # run and show stdout/stderr
121
+ samarth diagnostics samarth_output/ # print build manifest
122
+ ```
123
+
124
+ ### Build modes
125
+
126
+ **universal** — copies source and precompiles `.pyc`. No external tools
127
+ needed. Works on every CPython 3.10–3.13 environment including Pydroid.
128
+ Provides no meaningful protection, just bytecode instead of source.
129
+
130
+ **pyarmor** — PyArmor bytecode encryption. Output requires the
131
+ `pyarmor_runtime_*` package at runtime. Supports cross-compilation via
132
+ `--platform` (see PyArmor docs). The only practical option for Pydroid and
133
+ the safer Termux choice.
134
+
135
+ **nuitka** — Nuitka compiles source to native code. No PyArmor layer.
136
+ Requires a C compiler. On Termux, only `--mode module` is supported
137
+ (Nuitka 2.6.7+). Not available on Pydroid.
138
+
139
+ **combined** — PyArmor encrypts first, Nuitka compiles the result. Strongest
140
+ desktop protection. Not supported on Android because Nuitka needs a full
141
+ native toolchain Android doesn't provide in Termux/Pydroid.
142
+
143
+ **termux-native** — Must run inside Termux on the target device. Runs
144
+ PyArmor with the correct `linux.*` platform string (per PyArmor's own Termux
145
+ notes, issue #1674), then optionally compiles with Nuitka `--module`. Cross-
146
+ compiling from your VPS and copying the result to Termux will not work.
147
+
148
+ **pydroid-compat** — Falls back to Universal Python mode by default.
149
+ Optionally attempts PyArmor with `--attempt-pyarmor`, but this is unverified
150
+ against Pydroid's own Python build and may fail at runtime.
151
+
152
+ ## Build output
153
+
154
+ Every build creates `samarth_output/` (or `--output DIR`) containing:
155
+ - The compiled/protected files
156
+ - `samarth_manifest.json` — records what was built, on what machine,
157
+ and explicitly notes which platforms have not been tested
158
+
159
+ The manifest is honest: a successful build on Linux x86_64 is not evidence
160
+ the output runs on Termux ARM64. Test on each target separately.
161
+
162
+ ## Packaging for PyPI
163
+
164
+ ```bash
165
+ pip install build twine
166
+ python -m build
167
+ twine upload dist/*
168
+ ```
169
+
170
+ If shipping a PyArmor-protected extension, include the runtime folder:
171
+
172
+ ```toml
173
+ [tool.setuptools.package-data]
174
+ "your_package" = ["*.so", "*.pyd", "pyarmor_runtime_*/**"]
175
+ ```
176
+
177
+ First upload: create a PyPI account, generate an API token under Account
178
+ Settings → API tokens, then use `__token__` as the username and the token
179
+ as the password when twine prompts.
180
+
181
+ ## Runtime checks
182
+
183
+ ```python
184
+ from samarth.guard import run_all
185
+
186
+ run_all(
187
+ min_python=(3, 10),
188
+ max_python=(3, 13),
189
+ allowed_platforms=("Linux", "Windows", "Darwin"),
190
+ )
191
+ ```
192
+
193
+ For integrity verification, compute the hash once after your final build:
194
+
195
+ ```bash
196
+ python -c "import hashlib; print(hashlib.sha256(open('app.py','rb').read()).hexdigest())"
197
+ ```
198
+
199
+ Then pass it to `run_all`:
200
+
201
+ ```python
202
+ run_all(expected_sha256="<hash>", file_path=__file__)
203
+ ```
204
+
205
+ Every check exits with status 1 and a message on failure. None of this
206
+ resists a determined reverse engineer — it catches version mismatches and
207
+ casual debugging.
208
+
209
+ ## Running tests
210
+
211
+ ```bash
212
+ python -m unittest discover -v tests/
213
+ ```
214
+
215
+ All 13 tests run without PyArmor or Nuitka installed. Tests that require
216
+ those tools or specific hardware (Termux, Pydroid, ARM64) are marked
217
+ with `skipTest` where the environment isn't detected.
218
+
219
+ ## Troubleshooting
220
+
221
+ **`'pyarmor' not found on PATH`** — `pip install pyarmor`, confirm
222
+ `pyarmor --version` works in the same shell.
223
+
224
+ **`'nuitka' not found on PATH`** — `pip install nuitka`, and confirm a C
225
+ compiler is installed (see Install section above).
226
+
227
+ **`pyarmor produced no output`** — run `pyarmor gen` directly on your
228
+ source to see the raw error. Usually a missing activation or empty input.
229
+
230
+ **PyArmor `.so` load error in Termux** — apply the `patchelf` fix shown
231
+ in the Install section above.
232
+
233
+ **`'<name>' not found in PyArmor output`** — PyArmor renamed the entry
234
+ file. Use `samarth build ... --entry <actual-name>`.
235
+
236
+ **Output runs on build machine but not on target** — compiled output is
237
+ tied to OS, architecture, and Python version. Build on each target, or
238
+ for PyArmor use cross-platform `--platform` flags.
239
+
240
+ ## License
241
+
242
+ MIT
@@ -0,0 +1,223 @@
1
+ # SAMARTH ENC
2
+
3
+ A Python build tool that chains multiple protection strategies — PyArmor
4
+ bytecode encryption, Nuitka native compilation, or both — into one command.
5
+ It auto-detects your environment and picks the strongest strategy that
6
+ actually works there, rather than silently producing output that won't run.
7
+
8
+ ## Platform support
9
+
10
+ | Platform | Universal | PyArmor | Nuitka | Combined |
11
+ |---|---|---|---|---|
12
+ | Linux x86_64 | ✓ | ✓ | ✓ | ✓ |
13
+ | Linux ARM64 | ✓ | ✓ | ✓ | ✓ |
14
+ | Windows x86_64 | ✓ | ✓ | ✓ | ✓ |
15
+ | macOS x86_64/ARM64 | ✓ | ✓ | ✓ | ✓ |
16
+ | Termux (ARM64) | ✓ | ✓ (linux.aarch64) | ✓ (module only, Nuitka 2.6.7+) | ✗ |
17
+ | Pydroid 3 | ✓ | Experimental | ✗ | ✗ |
18
+
19
+ **Notes:**
20
+ - Nuitka standalone/onefile builds don't work reliably on Termux due to
21
+ Android's dynamic linker not matching standard Linux assumptions.
22
+ - Pydroid has no accessible C compiler. PyArmor works experimentally there
23
+ (its Android runtime is built for Termux/NDK Python, not Pydroid's own
24
+ build — test before shipping).
25
+ - Cross-compiled artifacts are never portable. Build on the target device or
26
+ use PyArmor's `--platform` flag for cross-compilation.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install samarth
32
+ ```
33
+
34
+ If you want PyArmor and/or Nuitka protection (not just Universal mode):
35
+
36
+ ```bash
37
+ pip install pyarmor nuitka
38
+ ```
39
+
40
+ Nuitka requires a C compiler:
41
+
42
+ ```bash
43
+ # Debian/Ubuntu/VPS
44
+ sudo apt install build-essential patchelf
45
+
46
+ # Termux
47
+ pkg install clang patchelf
48
+
49
+ # Windows — Nuitka will offer to download MinGW64 on first run
50
+ # macOS
51
+ xcode-select --install
52
+ ```
53
+
54
+ **Termux-specific PyArmor fix** (if you get a `.so` load error):
55
+
56
+ ```bash
57
+ patchelf --add-needed libpython3.11.so.0.1 \
58
+ $(python -c "import pyarmor; print(__import__('pathlib').Path(pyarmor.__file__).parent)")/cli/core/android/aarch64/pytransform3.so
59
+ ```
60
+
61
+ Replace `3.11` with your actual Python version.
62
+
63
+ ## Usage
64
+
65
+ ### Interactive menu
66
+
67
+ ```
68
+ samarth
69
+ ```
70
+
71
+ ```
72
+ SAMARTH ENC
73
+
74
+ [1] Universal Python Build
75
+ [2] PyArmor Protection
76
+ [3] Native Compilation
77
+ [4] PyArmor + Nuitka
78
+ [5] Termux Build
79
+ [6] Pydroid Compatibility Build
80
+ [7] Automatic Platform Detection
81
+ [8] Compatibility Checker
82
+ [9] Dependency Checker
83
+ [10] Integrity Checker
84
+ [11] Debug Protected File
85
+ [12] Build Diagnostics
86
+ [0] Exit
87
+ ```
88
+
89
+ ### CLI subcommands
90
+
91
+ ```bash
92
+ samarth build app.py # auto-select best mode
93
+ samarth build app.py --mode pyarmor # specific mode
94
+ samarth build mypackage/ --mode combined --output dist/
95
+
96
+ samarth detect # show OS/arch/tool report
97
+ samarth check # show which modes work here
98
+ samarth deps # check tool availability
99
+
100
+ samarth integrity app.py <sha256-hash> # verify file hasn't changed
101
+ samarth debug dist/app.py # run and show stdout/stderr
102
+ samarth diagnostics samarth_output/ # print build manifest
103
+ ```
104
+
105
+ ### Build modes
106
+
107
+ **universal** — copies source and precompiles `.pyc`. No external tools
108
+ needed. Works on every CPython 3.10–3.13 environment including Pydroid.
109
+ Provides no meaningful protection, just bytecode instead of source.
110
+
111
+ **pyarmor** — PyArmor bytecode encryption. Output requires the
112
+ `pyarmor_runtime_*` package at runtime. Supports cross-compilation via
113
+ `--platform` (see PyArmor docs). The only practical option for Pydroid and
114
+ the safer Termux choice.
115
+
116
+ **nuitka** — Nuitka compiles source to native code. No PyArmor layer.
117
+ Requires a C compiler. On Termux, only `--mode module` is supported
118
+ (Nuitka 2.6.7+). Not available on Pydroid.
119
+
120
+ **combined** — PyArmor encrypts first, Nuitka compiles the result. Strongest
121
+ desktop protection. Not supported on Android because Nuitka needs a full
122
+ native toolchain Android doesn't provide in Termux/Pydroid.
123
+
124
+ **termux-native** — Must run inside Termux on the target device. Runs
125
+ PyArmor with the correct `linux.*` platform string (per PyArmor's own Termux
126
+ notes, issue #1674), then optionally compiles with Nuitka `--module`. Cross-
127
+ compiling from your VPS and copying the result to Termux will not work.
128
+
129
+ **pydroid-compat** — Falls back to Universal Python mode by default.
130
+ Optionally attempts PyArmor with `--attempt-pyarmor`, but this is unverified
131
+ against Pydroid's own Python build and may fail at runtime.
132
+
133
+ ## Build output
134
+
135
+ Every build creates `samarth_output/` (or `--output DIR`) containing:
136
+ - The compiled/protected files
137
+ - `samarth_manifest.json` — records what was built, on what machine,
138
+ and explicitly notes which platforms have not been tested
139
+
140
+ The manifest is honest: a successful build on Linux x86_64 is not evidence
141
+ the output runs on Termux ARM64. Test on each target separately.
142
+
143
+ ## Packaging for PyPI
144
+
145
+ ```bash
146
+ pip install build twine
147
+ python -m build
148
+ twine upload dist/*
149
+ ```
150
+
151
+ If shipping a PyArmor-protected extension, include the runtime folder:
152
+
153
+ ```toml
154
+ [tool.setuptools.package-data]
155
+ "your_package" = ["*.so", "*.pyd", "pyarmor_runtime_*/**"]
156
+ ```
157
+
158
+ First upload: create a PyPI account, generate an API token under Account
159
+ Settings → API tokens, then use `__token__` as the username and the token
160
+ as the password when twine prompts.
161
+
162
+ ## Runtime checks
163
+
164
+ ```python
165
+ from samarth.guard import run_all
166
+
167
+ run_all(
168
+ min_python=(3, 10),
169
+ max_python=(3, 13),
170
+ allowed_platforms=("Linux", "Windows", "Darwin"),
171
+ )
172
+ ```
173
+
174
+ For integrity verification, compute the hash once after your final build:
175
+
176
+ ```bash
177
+ python -c "import hashlib; print(hashlib.sha256(open('app.py','rb').read()).hexdigest())"
178
+ ```
179
+
180
+ Then pass it to `run_all`:
181
+
182
+ ```python
183
+ run_all(expected_sha256="<hash>", file_path=__file__)
184
+ ```
185
+
186
+ Every check exits with status 1 and a message on failure. None of this
187
+ resists a determined reverse engineer — it catches version mismatches and
188
+ casual debugging.
189
+
190
+ ## Running tests
191
+
192
+ ```bash
193
+ python -m unittest discover -v tests/
194
+ ```
195
+
196
+ All 13 tests run without PyArmor or Nuitka installed. Tests that require
197
+ those tools or specific hardware (Termux, Pydroid, ARM64) are marked
198
+ with `skipTest` where the environment isn't detected.
199
+
200
+ ## Troubleshooting
201
+
202
+ **`'pyarmor' not found on PATH`** — `pip install pyarmor`, confirm
203
+ `pyarmor --version` works in the same shell.
204
+
205
+ **`'nuitka' not found on PATH`** — `pip install nuitka`, and confirm a C
206
+ compiler is installed (see Install section above).
207
+
208
+ **`pyarmor produced no output`** — run `pyarmor gen` directly on your
209
+ source to see the raw error. Usually a missing activation or empty input.
210
+
211
+ **PyArmor `.so` load error in Termux** — apply the `patchelf` fix shown
212
+ in the Install section above.
213
+
214
+ **`'<name>' not found in PyArmor output`** — PyArmor renamed the entry
215
+ file. Use `samarth build ... --entry <actual-name>`.
216
+
217
+ **Output runs on build machine but not on target** — compiled output is
218
+ tied to OS, architecture, and Python version. Build on each target, or
219
+ for PyArmor use cross-platform `--platform` flags.
220
+
221
+ ## License
222
+
223
+ MIT
@@ -0,0 +1,35 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "samarth"
7
+ version = "0.2.0"
8
+ description = "Multi-platform Python protection pipeline — PyArmor, Nuitka, and pure-Python modes"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10,<3.14"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Samarth", email = "creatorpc@proton.me" }
14
+ ]
15
+ dependencies = [
16
+ "pyarmor>=9.0",
17
+ "nuitka>=2.0",
18
+ ]
19
+ classifiers = [
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Operating System :: OS Independent",
25
+ "Topic :: Software Development :: Build Tools",
26
+ ]
27
+
28
+ [project.optional-dependencies]
29
+ dev = ["pytest"]
30
+
31
+ [project.scripts]
32
+ samarth = "samarth.cli:main"
33
+
34
+ [tool.setuptools.package-data]
35
+ "samarth" = ["py.typed"]
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
@@ -0,0 +1,105 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import shutil
5
+ import tempfile
6
+ import time
7
+ from dataclasses import asdict, dataclass
8
+ from pathlib import Path
9
+
10
+ from samarth.detect import Environment, detect_environment
11
+ from samarth.strategies import STRATEGIES, StrategyError, UnsupportedPlatform, pick_best_strategy
12
+
13
+ BuildError = StrategyError # same thing, kept importable under the old name too
14
+
15
+
16
+ @dataclass
17
+ class BuildResult:
18
+ mode: str
19
+ output_dir: Path
20
+ source: Path
21
+ environment: Environment
22
+ tested_here: bool
23
+ manifest_path: Path
24
+
25
+
26
+ def _copy_output(compiled: Path, output: str | None) -> Path:
27
+ dest = Path(output).resolve() if output else Path("samarth_output").resolve()
28
+ dest.mkdir(parents=True, exist_ok=True)
29
+ for item in compiled.iterdir():
30
+ target = dest / item.name
31
+ if target.exists():
32
+ shutil.rmtree(target) if target.is_dir() else target.unlink()
33
+ shutil.move(str(item), str(target))
34
+ return dest
35
+
36
+
37
+ def _validate(output_dir: Path) -> list[str]:
38
+ problems = []
39
+ if not output_dir.exists() or not any(output_dir.iterdir()):
40
+ problems.append("output directory is empty")
41
+ return problems
42
+
43
+
44
+ def _write_manifest(dest: Path, mode: str, env: Environment, source: Path, problems: list[str]) -> Path:
45
+ manifest = {
46
+ "samarth_mode": mode,
47
+ "source": str(source),
48
+ "built_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
49
+ "build_environment": {
50
+ "os": env.os_name,
51
+ "python": f"{env.python_implementation} {'.'.join(map(str, env.python_version))}",
52
+ "arch": env.arch,
53
+ "is_termux": env.is_termux,
54
+ "is_pydroid": env.is_pydroid,
55
+ "pyarmor_version": env.pyarmor_version,
56
+ "nuitka_version": env.nuitka_version,
57
+ },
58
+ "validated": not problems,
59
+ "validation_problems": problems,
60
+ "tested_platforms": [env.os_name + "." + env.arch],
61
+ "untested_platforms_note": (
62
+ "This manifest only reflects a build on the machine listed above. "
63
+ "It is not proof the output runs on any other OS, architecture, "
64
+ "or Python build -- including other Android environments."
65
+ ),
66
+ }
67
+ path = dest / "samarth_manifest.json"
68
+ path.write_text(json.dumps(manifest, indent=2))
69
+ return path
70
+
71
+
72
+ def run(source: str, mode: str | None, output: str | None, **strategy_kwargs) -> BuildResult:
73
+ src = Path(source).resolve()
74
+ if not src.exists():
75
+ raise StrategyError(f"source path does not exist: {src}")
76
+
77
+ env = detect_environment()
78
+ chosen = mode or pick_best_strategy(env)
79
+ if chosen not in STRATEGIES:
80
+ raise StrategyError(f"unknown mode '{chosen}', choose from: {', '.join(STRATEGIES)}")
81
+
82
+ spec = STRATEGIES[chosen]
83
+ compatible, reason = spec["compatible"](env)
84
+ if not compatible:
85
+ raise UnsupportedPlatform(f"'{chosen}' is not usable here: {reason}")
86
+
87
+ workdir = Path(tempfile.mkdtemp(prefix="samarth-"))
88
+ try:
89
+ compiled = spec["func"](src, workdir, env, **strategy_kwargs)
90
+ dest = _copy_output(compiled, output)
91
+ finally:
92
+ shutil.rmtree(workdir, ignore_errors=True)
93
+
94
+ problems = _validate(dest)
95
+ manifest_path = _write_manifest(dest, chosen, env, src, problems)
96
+
97
+ return BuildResult(
98
+ mode=chosen,
99
+ output_dir=dest,
100
+ source=src,
101
+ environment=env,
102
+ tested_here=not problems,
103
+ manifest_path=manifest_path,
104
+ )
105
+