portablepy 0.1.0__py3-none-any.whl

portablepy/__init__.py

@@ -0,0 +1,3 @@
+"""Portable application bundles with verified wheels and an offline launcher."""
+
+__version__ = '0.1.0'

portablepy/__main__.py

@@ -0,0 +1,3 @@
+from portablepy.cli import main
+
+raise SystemExit(main())

portablepy/builder.py

@@ -0,0 +1,199 @@
+"""Assemble, validate, and archive a portable application."""
+
+from json import dumps
+from pathlib import Path
+from re import fullmatch
+from subprocess import run
+from tarfile import open as open_tar
+from importlib.resources import files
+from tempfile import TemporaryDirectory
+from portablepy.discovery import discover
+from zipfile import ZipFile, ZIP_DEFLATED
+from portablepy.models import BuildOptions
+from portablepy.bytecode import compile_tree
+from portablepy.shortcuts import write_shortcut
+from portablepy.publishing import publish_archive
+from portablepy.files import copy_sources, include_data
+from portablepy.output import default_output, output_excludes, validate_output
+from portablepy.launcher import MANIFEST, file_hash, contents_hash, SCHEMA_VERSION
+from portablepy.wheels import collect_wheels, repack_bytecode, wheel_inventory, write_requirements
+
+RUNTIME_FIELDS = (
+    'implementation',
+    'version',
+    'platform',
+    'machine',
+    'bits',
+    'free_threaded',
+    'cache_tag',
+    'magic',
+)
+INSTRUCTIONS = """Portable Python application
+
+Extract this entire folder somewhere writable. Python itself is not included.
+Run: python run.py
+Extra arguments are forwarded to the application: python run.py --help
+
+You can also use the included console launcher: run.cmd on Windows,
+run.command on macOS, or run.sh on Linux. Double-click it to start; Linux
+file managers may require enabling executable scripts or choosing Run.
+If extraction removed executable permissions, run chmod +x run.command
+or chmod +x run.sh. Arguments supplied in a terminal are forwarded.
+Failed launches wait for a key/Enter when started without arguments
+(on Unix, only with an interactive terminal).
+
+The first launch installs the bundled wheels into a private .venv without
+network access. Use the matching CPython version and platform in bundle.json.
+Your Python installation needs the standard venv and ensurepip modules.
+
+Writable files live in data/. Defaults ship in seeds/ and are copied only when
+missing. Extract updates into the same folder to keep your data/.
+Moving the folder or changing the bundle rebuilds only the private environment.
+The application directory is named with a SHA-256 hash of its files and paths.
+The launcher finds it automatically; its name is recorded in bundle.json.
+
+python run.py --portable-info    Show bundle metadata without setup
+python run.py --portable-setup   Set up without starting the application
+python run.py --portable-verify  Verify immutable files without starting it
+
+Wheel versions and SHA-256 hashes are pinned in requirements.txt. Checksums
+detect corruption; they are not publisher signatures. Licenses for dependencies
+are retained in their wheels. Bytecode is version-specific, not encryption.
+"""
+
+
+def _python_command(command):
+    if not command:
+        raise ValueError('Provide the application command with --run')
+    first = command[0]
+    if any(argument in ('&&', '||', '|', '>', '<', ';') for argument in command):
+        raise ValueError('Commands are argument lists, not shell scripts')
+    if first == '{python}' or fullmatch(r'python(?:3(?:\.\d+)?)?(?:\.exe)?', first):
+        return True
+    if Path(first).name != first or '/' in first or '\\' in first:
+        raise ValueError('Use python, {python}, or an installed console command as the executable')
+    return False
+
+
+def build_bundle(options: BuildOptions) -> Path:
+    if options.compile_mode not in ('none', 'app', 'all'):
+        raise ValueError('--compile must be none, app, or all')
+    if options.strip_source and options.compile_mode == 'none':
+        raise ValueError('--strip-source requires --compile app or --compile all')
+    python_command = _python_command(options.command)
+    output = options.output.expanduser().absolute() if options.output is not None else None
+    if output is not None:
+        validate_output(output, replace=options.replace)
+    discovery = discover(options)
+    if output is None:
+        output = default_output(discovery, options.command)
+        validate_output(output, replace=options.replace)
+    if discovery.unresolved:
+        raise ValueError(
+            'Unresolved or ambiguous imports: '
+            + ', '.join(discovery.unresolved)
+            + '. Install them in the selected environment, or declare dependencies with --requirement/--requirements.'
+        )
+    print(f'Using {discovery.python}; dependency source: {discovery.mode}', flush=True)
+    name = output.name.removesuffix('.tar.gz').removesuffix('.zip')
+    if not fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*', name):
+        raise ValueError('Archive name must use letters, numbers, dots, underscores, or hyphens')
+    with TemporaryDirectory(prefix='portablepy-build-') as temporary:
+        work = Path(temporary)
+        bundle = work / name
+        app = bundle / 'app'
+        app.mkdir(parents=True)
+        (bundle / 'data').mkdir()
+        source_copy = work / 'source'
+        if discovery.mode == 'project':
+            copy_sources(
+                discovery.source,
+                source_copy,
+                (*options.excludes, *output_excludes(discovery.source, output)),
+            )
+        else:
+            source_copy.mkdir()
+        copy_sources(discovery.source, app, paths=discovery.application_files)
+        wheels = bundle / 'wheels'
+        collect_wheels(discovery, options, wheels, source_copy)
+        if options.compile_mode != 'none':
+            compile_tree(app, discovery.python, strip=options.strip_source)
+        if options.compile_mode == 'all':
+            for wheel in sorted(wheels.glob('*.whl')):
+                repack_bytecode(
+                    wheel, discovery.python, discovery.runtime, strip=options.strip_source
+                )
+        app_directory = contents_hash(
+            {
+                path.relative_to(app).as_posix(): file_hash(path)
+                for path in app.rglob('*')
+                if path.is_file()
+            }
+        )
+        renamed = bundle / app_directory
+        if not app.resolve().is_relative_to(
+            bundle.resolve()
+        ) or not renamed.resolve().is_relative_to(bundle.resolve()):
+            raise ValueError('Application directory must stay inside the bundle')
+        app.rename(renamed)
+        count = write_requirements(wheels, bundle / 'requirements.txt')
+        base = discovery.source if discovery.source.is_dir() else discovery.source.parent
+        seeds = include_data(options.includes, base, bundle)
+        (bundle / 'run.py').write_bytes(files('portablepy').joinpath('launcher.py').read_bytes())
+        compiled_launcher = options.compile_mode == 'all'
+        launcher = 'run.pyc' if compiled_launcher else 'run.py'
+        if compiled_launcher:
+            compile_tree(bundle / 'run.py', discovery.python, strip=options.strip_source)
+        shortcut = write_shortcut(bundle, discovery.runtime, compiled=compiled_launcher)
+        (bundle / 'README.txt').write_text(
+            INSTRUCTIONS.replace('run.py', launcher), encoding='utf-8'
+        )
+        checksums = {
+            path.relative_to(bundle).as_posix(): file_hash(path)
+            for path in sorted(bundle.rglob('*'))
+            if path.is_file()
+        }
+        manifest = {
+            'schema': SCHEMA_VERSION,
+            'name': name,
+            'app_directory': app_directory,
+            'runtime': {key: discovery.runtime[key] for key in RUNTIME_FIELDS},
+            'command': list(options.command),
+            'python_command': python_command,
+            'prefer_installed': discovery.mode in ('project', 'wheel'),
+            'compile': options.compile_mode,
+            'strip_source': options.strip_source,
+            'files': checksums,
+            'seed_files': seeds,
+            'dependencies': wheel_inventory(wheels),
+            'profile': options.profile,
+        }
+        manifest['build_id'] = contents_hash(manifest)
+        (bundle / MANIFEST).write_text(dumps(manifest, indent=2) + '\n', encoding='utf-8')
+        (bundle / f'{MANIFEST}.sha256').write_text(
+            file_hash(bundle / MANIFEST) + '\n', encoding='utf-8'
+        )
+        print(f'Validating {count} wheels in an offline environment...', flush=True)
+        run([str(discovery.python), '-I', str(bundle / launcher), '--portable-setup'], check=True)
+        members = [*checksums, MANIFEST, f'{MANIFEST}.sha256']
+        output.parent.mkdir(parents=True, exist_ok=True)
+        # Publish only after validation; exclude the generated environment entirely.
+        staged = work / output.name
+        if output.name.endswith('.zip'):
+            with ZipFile(staged, 'w', compression=ZIP_DEFLATED) as archive:
+                for relative in sorted(members):
+                    archive.write(bundle / relative, f'{name}/{relative}')
+                    if relative == shortcut and shortcut != 'run.cmd':
+                        entry = archive.getinfo(f'{name}/{relative}')
+                        entry.create_system = 3
+                        entry.external_attr = 0o100755 << 16
+        else:
+            with open_tar(staged, 'w:gz') as archive:
+                for relative in sorted(members):
+                    member = archive.gettarinfo(bundle / relative, arcname=f'{name}/{relative}')
+                    if relative == shortcut and shortcut != 'run.cmd':
+                        member.mode = 0o755
+                    with (bundle / relative).open('rb') as stream:
+                        archive.addfile(member, stream)
+        publish_archive(staged, output, replace=options.replace)
+    return output

portablepy/bytecode.py

@@ -0,0 +1,29 @@
+"""Compile application and wheel sources with the selected interpreter."""
+
+from pathlib import Path
+from subprocess import run
+
+COMPILE = """
+from sys import argv
+from pathlib import Path
+from py_compile import compile, PycInvalidationMode
+from importlib.util import cache_from_source
+root, strip = Path(argv[1]), argv[2] == 'strip'
+single = root.is_file()
+for path in [root] if single else sorted(root.rglob('*.py')):
+    relative = Path(path.name) if single else path.relative_to(root)
+    if '__pycache__' in relative.parts or any(part.endswith('.dist-info') for part in relative.parts):
+        continue
+    if any(part.endswith('.data') for part in relative.parts) and 'scripts' in relative.parts:
+        continue
+    output = str(path.with_suffix('.pyc')) if strip or single else cache_from_source(str(path))
+    compile(str(path), cfile=output, dfile=relative.as_posix(), doraise=True,
+            invalidation_mode=PycInvalidationMode.CHECKED_HASH)
+    if strip:
+        path.unlink()
+"""
+
+
+def compile_tree(root: Path, python: Path, *, strip=False):
+    """Compile a directory, or a single launcher to an adjacent executable .pyc."""
+    run([str(python), '-I', '-c', COMPILE, str(root), 'strip' if strip else 'keep'], check=True)

portablepy/cli.py

@@ -0,0 +1,175 @@
+"""Argly commands for building and checking bundles."""
+
+from json import dumps
+from sys import stderr
+from pathlib import Path
+from tarfile import TarError
+from zipfile import BadZipFile
+from subprocess import CalledProcessError
+from portablepy.builder import build_bundle
+from portablepy.verify import verify_bundle
+from typing import Any, Optional, Annotated
+from portablepy.config import resolve_options
+from portablepy.inspection import inspection_report
+from argly import App, Flag, Option, command, Argument
+
+
+EMPTY_OPTIONS: Any = ()  # Argly accepts tuples as defaults and passes fresh lists to handlers.
+
+
+@command('build', summary='Build a verified portable application archive.')
+def build(
+    source: Annotated[Optional[Path], Argument()] = None,
+    *,
+    run: Annotated[
+        Optional[str], Option('--command', help='Application command, such as python -m my_app.')
+    ] = None,
+    profile: Annotated[
+        Optional[str], Option(help='Named build profile from pyproject.toml.')
+    ] = None,
+    config: Annotated[
+        Optional[Path], Option(help='Explicit pyproject.toml configuration file.')
+    ] = None,
+    output: Annotated[
+        Optional[Path],
+        Option(
+            '-o',
+            help='Archive path; defaults to a platform-specific name in the current directory.',
+        ),
+    ] = None,
+    python: Annotated[
+        Optional[Path], Option(help='Target interpreter; defaults to the project .venv.')
+    ] = None,
+    requirement: Annotated[
+        list[str], Option(help='Additional package requirement.')
+    ] = EMPTY_OPTIONS,
+    requirements: Annotated[list[Path], Option(help='Requirements file.')] = EMPTY_OPTIONS,
+    extra: Annotated[list[str], Option(help='Packaged application extra.')] = EMPTY_OPTIONS,
+    include: Annotated[
+        list[str], Option(help='Seed file or directory: SOURCE=data/DESTINATION.')
+    ] = EMPTY_OPTIONS,
+    exclude: Annotated[list[str], Option(help='Source exclusion glob.')] = EMPTY_OPTIONS,
+    find_links: Annotated[
+        list[str], Option(help='Local wheel directory or package listing URL.')
+    ] = EMPTY_OPTIONS,
+    no_index: Annotated[bool, Flag(help='Resolve from local packages only.')] = False,
+    compile_mode: Annotated[
+        Optional[str],
+        Option(
+            '--compile',
+            choices=('none', 'app', 'all'),
+            help='Bytecode scope; all includes wheels and launcher.',
+        ),
+    ] = None,
+    strip_source: Annotated[
+        bool, Flag(help='Remove compiled .py files; requires --compile.')
+    ] = False,
+    keep_source: Annotated[bool, Flag(help='Keep sources, overriding a profile.')] = False,
+    use_index: Annotated[bool, Flag(help='Allow index access, overriding a profile.')] = False,
+    replace: Annotated[
+        bool, Flag(help='Replace an archive only after the new build passes validation.')
+    ] = False,
+    no_replace: Annotated[bool, Flag(help='Refuse replacement, overriding a profile.')] = False,
+) -> int:
+    for enabled, disabled, label in (
+        (strip_source, keep_source, 'strip-source/keep-source'),
+        (no_index, use_index, 'no-index/use-index'),
+        (replace, no_replace, 'replace/no-replace'),
+    ):
+        if enabled and disabled:
+            raise ValueError(f'Choose only one of --{label.replace("/", " and --")}')
+    options = resolve_options(
+        source,
+        profile=profile,
+        config=config,
+        **{
+            'run': run,
+            'output': output,
+            'python': python,
+            'requirement': requirement or None,
+            'requirements': requirements or None,
+            'extra': extra or None,
+            'include': include or None,
+            'exclude': exclude or None,
+            'find-links': find_links or None,
+            'compile': compile_mode,
+            'no-index': False if use_index else True if no_index else None,
+            'strip-source': False if keep_source else True if strip_source else None,
+            'replace': False if no_replace else True if replace else None,
+        },
+    )
+    path = build_bundle(options)
+    print(f'Created {path} ({path.stat().st_size:,} bytes)')
+    return 0
+
+
+@command('inspect', summary='Explain included files, dependencies, and estimated bundle size.')
+def inspect(
+    source: Annotated[Optional[Path], Argument()] = None,
+    *,
+    python: Annotated[Optional[Path], Option()] = None,
+    run: Annotated[Optional[str], Option(help='Use the same launch command as the build.')] = None,
+    output: Annotated[Optional[Path], Option('-o', help='Planned archive path.')] = None,
+    profile: Annotated[Optional[str], Option(help='Named build profile.')] = None,
+    config: Annotated[
+        Optional[Path], Option(help='Explicit pyproject.toml configuration file.')
+    ] = None,
+    requirement: Annotated[list[str], Option()] = EMPTY_OPTIONS,
+    requirements: Annotated[list[Path], Option()] = EMPTY_OPTIONS,
+    extra: Annotated[list[str], Option()] = EMPTY_OPTIONS,
+    include: Annotated[list[str], Option()] = EMPTY_OPTIONS,
+    exclude: Annotated[list[str], Option()] = EMPTY_OPTIONS,
+    find_links: Annotated[list[str], Option()] = EMPTY_OPTIONS,
+    no_index: Annotated[bool, Flag()] = False,
+    use_index: Annotated[bool, Flag()] = False,
+    compile_mode: Annotated[
+        Optional[str], Option('--compile', choices=('none', 'app', 'all'))
+    ] = None,
+    strip_source: Annotated[bool, Flag()] = False,
+    keep_source: Annotated[bool, Flag()] = False,
+    resolve: Annotated[
+        bool,
+        Flag(help='Resolve/build wheels for exact dependency details and a fuller size estimate.'),
+    ] = False,
+) -> int:
+    if (no_index and use_index) or (strip_source and keep_source):
+        raise ValueError('Choose only one of each opposing flag pair')
+    options = resolve_options(
+        source,
+        profile=profile,
+        config=config,
+        **{
+            'python': python,
+            'run': run,
+            'output': output,
+            'requirement': requirement or None,
+            'requirements': requirements or None,
+            'extra': extra or None,
+            'include': include or None,
+            'exclude': exclude or None,
+            'find-links': find_links or None,
+            'compile': compile_mode,
+            'no-index': False if use_index else True if no_index else None,
+            'strip-source': False if keep_source else True if strip_source else None,
+        },
+    )
+    report = inspection_report(options, resolve=resolve)
+    print(dumps(report, indent=2))
+    return 1 if report['unresolved_imports'] else 0
+
+
+@command('verify', summary='Check an archive or extracted bundle without running the application.')
+def verify(bundle: Annotated[Path, Argument()]) -> int:
+    manifest = verify_bundle(bundle)
+    print(f'Checksums passed: {manifest["name"]}')
+    return 0
+
+
+def main() -> int:
+    try:
+        return App.discover('portablepy', 'portablepy.cli').run()
+    except KeyboardInterrupt:
+        return 130
+    except (OSError, ValueError, KeyError, TarError, BadZipFile, CalledProcessError) as error:
+        print(f'portablepy: {error}', file=stderr)
+        return 1

portablepy/config.py

@@ -0,0 +1,128 @@
+"""Read build defaults and profiles without changing the caller's working directory."""
+
+from shlex import split
+from pathlib import Path
+from tomllib import loads
+from typing import Optional
+from portablepy.models import BuildOptions
+
+LIST_KEYS = {'requirement', 'requirements', 'extra', 'include', 'exclude', 'find-links'}
+BOOL_KEYS = {'no-index', 'strip-source', 'replace'}
+TEXT_KEYS = {'source', 'run', 'output', 'python', 'compile'}
+CONFIG_KEYS = LIST_KEYS | BOOL_KEYS | TEXT_KEYS
+
+
+def _validate(settings, label):
+    if not isinstance(settings, dict):
+        raise ValueError(f'{label} must be a TOML table')
+    unknown = settings.keys() - CONFIG_KEYS
+    if unknown:
+        raise ValueError(f'Unknown {label} settings: {", ".join(sorted(unknown))}')
+    for key, value in settings.items():
+        if key in LIST_KEYS:
+            valid = isinstance(value, list) and all(isinstance(item, str) for item in value)
+        elif key in BOOL_KEYS:
+            valid = type(value) is bool
+        else:
+            valid = isinstance(value, str) and bool(value)
+        if not valid:
+            raise ValueError(f'Invalid {label}.{key}')
+    if settings.get('compile', 'none') not in ('none', 'app', 'all'):
+        raise ValueError(f'{label}.compile must be none, app, or all')
+
+
+def _config_file(source, explicit):
+    if explicit is not None:
+        path = explicit.expanduser().resolve()
+        if not path.is_file():
+            raise ValueError(f'Configuration file does not exist: {path}')
+        return path
+    start = source.expanduser().resolve() if source is not None else Path.cwd()
+    if start.is_file():
+        start = start.parent
+    for folder in (start, *start.parents):
+        path = folder / 'pyproject.toml'
+        if path.is_file():
+            return path
+    return None
+
+
+def resolve_options(
+    source: Optional[Path] = None,
+    *,
+    profile: Optional[str] = None,
+    config: Optional[Path] = None,
+    **overrides,
+) -> BuildOptions:
+    path = _config_file(source, config)
+    settings = {}
+    if path is not None:
+        tool = loads(path.read_text(encoding='utf-8')).get('tool', {})
+        if not isinstance(tool, dict):
+            raise ValueError('tool must be a TOML table')
+        settings = tool.get('portablepy', {})
+        if not isinstance(settings, dict):
+            raise ValueError('tool.portablepy must be a TOML table')
+        settings = dict(settings)
+    profiles = settings.pop('profiles', {})
+    if not isinstance(profiles, dict):
+        raise ValueError('tool.portablepy.profiles must be a TOML table')
+    _validate(settings, 'tool.portablepy')
+    for name, values in profiles.items():
+        _validate(values, f'tool.portablepy.profiles.{name}')
+    configured = bool(settings or profiles)
+    if profile is not None:
+        if profile not in profiles:
+            available = ', '.join(sorted(profiles)) or '(none)'
+            raise ValueError(f'Unknown profile {profile!r}; available profiles: {available}')
+        settings.update(profiles[profile])
+    base = path.parent if path is not None else Path.cwd()
+    for key in ('source', 'output', 'python'):
+        if key in settings:
+            settings[key] = (base / Path(settings[key]).expanduser()).absolute()
+    if 'requirement' in settings:
+        settings['requirement'] = [
+            str((base / Path(item).expanduser()).absolute())
+            if '://' not in item and (base / Path(item).expanduser()).exists()
+            else item
+            for item in settings['requirement']
+        ]
+    if 'requirements' in settings:
+        settings['requirements'] = [
+            (base / Path(item).expanduser()).resolve() for item in settings['requirements']
+        ]
+    if 'include' in settings:
+        includes = []
+        for item in settings['include']:
+            filename, separator, destination = item.partition('=')
+            if not separator:
+                raise ValueError('Configured include uses SOURCE=data/DESTINATION')
+            includes.append(str((base / Path(filename).expanduser()).resolve()) + '=' + destination)
+        settings['include'] = includes
+    if 'find-links' in settings:
+        settings['find-links'] = [
+            item if '://' in item else str((base / Path(item).expanduser()).resolve())
+            for item in settings['find-links']
+        ]
+    settings.update({key: value for key, value in overrides.items() if value is not None})
+    selected_source = (
+        source if source is not None else settings.get('source', base if configured else Path.cwd())
+    )
+    return BuildOptions(
+        source=Path(selected_source),
+        command=tuple(split(settings.get('run', ''))),
+        output=settings.get('output'),
+        python=settings.get('python'),
+        requirements=tuple(settings.get('requirement', ())),
+        requirement_files=tuple(Path(item) for item in settings.get('requirements', ())),
+        extras=tuple(settings.get('extra', ())),
+        includes=tuple(settings.get('include', ())),
+        excludes=tuple(settings.get('exclude', ())),
+        find_links=tuple(settings.get('find-links', ())),
+        no_index=settings.get('no-index', False),
+        compile_mode=settings.get('compile', 'none'),
+        strip_source=settings.get('strip-source', False),
+        replace=settings.get('replace', False),
+        profile=profile,
+        config=path if configured or config is not None else None,
+    )