Python API

Everything the CLI does is available programmatically:

from pathlib import Path

import sharepack

result = sharepack.build(Path("myproject"), Path("demo.html"))
print(result.n_files, "files,", result.size_bytes, "bytes")
for skipped in result.skipped:
    print("skipped:", skipped.path, "—", skipped.reason)

Errors are typed: build raises sharepack.ProjectError for a bad project path and sharepack.DetectionError when no supported framework is found — both subclasses of sharepack.SharepackError.

sharepack

sharepack: turn a local Python web app into a single shareable HTML file.

class sharepack.BuildResult(out, adapter_name, n_files, size_bytes, scrubbed, skipped, warnings, db_files, db_bytes)

Everything a build produced, for reporting or programmatic use.

Parameters:

• out (Path)

• adapter_name (str)

• n_files (int)

• size_bytes (int)

• scrubbed (list[str])

• skipped (list[SkippedFile])

• warnings (list[str])

• db_files (list[str])

• db_bytes (int)

out

Path of the written HTML file.

Type:

pathlib.Path

adapter_name

Name of the detected framework adapter.

Type:

str

n_files

Number of files bundled.

Type:

int

size_bytes

Size of the written HTML file in bytes.

Type:

int

scrubbed

Messages describing secret scrubbing that took place.

Type:

list[str]

skipped

Files that were not bundled, with reasons.

Type:

list[sharepack.collect.SkippedFile]

warnings

Compatibility and size warnings.

Type:

list[str]

db_files

Relative paths of bundled database files.

Type:

list[str]

db_bytes

Total size of bundled database files in bytes.

Type:

int

class sharepack.CollectionResult(files=<factory>, scrubbed=<factory>, skipped=<factory>)

Everything the collect pass learned about a project.

Parameters:

• files (dict[str, bytes])

• scrubbed (list[str])

• skipped (list[SkippedFile])

files

Bundled file contents keyed by relative path.

Type:

dict[str, bytes]

scrubbed

Messages describing secret scrubbing that took place.

Type:

list[str]

skipped

Files that were not bundled, with reasons.

Type:

list[sharepack.collect.SkippedFile]

property total_bytes: int

Total size of all bundled files in bytes.

property db_bytes: int

Total size of bundled database files in bytes.

exception sharepack.DetectionError

No supported framework could be detected in the project.

exception sharepack.ProjectError

The project path is missing or not a directory.

exception sharepack.SharepackError

Base class for all sharepack errors.

class sharepack.SkippedFile(path, reason)

A file that was not bundled, and why.

Parameters:

• path (str)

• reason (str)

sharepack.build(project, out, *, include=(), exclude=(), settings_module=None, app_spec=None, pyodide_version='0.26.4', pip_pin=None)

Bundle a project into a single self-contained HTML file.

Parameters:

• project (Path) – Project root directory (for Django: contains manage.py).

• out (Path) – Path of the HTML file to write.

• include (Sequence[str]) – Glob patterns forcing extra files into the bundle.

• exclude (Sequence[str]) – Glob patterns keeping files out of the bundle.

• settings_module (str | None) – Explicit Django settings module, bypassing detection from manage.py.

• app_spec (str | None) – Explicit module:variable locating a Flask or FastAPI app, bypassing entry-module scanning.

• pyodide_version (str) – Pyodide release loaded from the CDN at view time.

• pip_pin (str | None) – Override for the framework’s pip requirement string.

Returns:

A report of what was built.

Raises:

ProjectError – If project does not exist or is not a directory.

Return type:

BuildResult

Note

A DetectionError propagates from framework detection when no supported framework is found in project.

sharepack.collect(project, include=(), exclude=())

Collect a project’s files for bundling, scrubbing secrets.

Parameters:

• project (Path) – Project root directory to walk.

• include (Sequence[str]) – Glob patterns (against posix relative paths) that force files into the bundle even if their extension is not bundled by default. Secret exclusions still apply.

• exclude (Sequence[str]) – Glob patterns that keep files out of the bundle; they take precedence over everything else.

Returns:

The bundled files plus scrub and skip diagnostics.

Return type:

CollectionResult

sharepack.collect

Walk a project directory, collect files, scrub secrets.

class sharepack.collect.SkippedFile(path, reason)

A file that was not bundled, and why.

Parameters:

• path (str)

• reason (str)

class sharepack.collect.CollectionResult(files=<factory>, scrubbed=<factory>, skipped=<factory>)

Everything the collect pass learned about a project.

Parameters:

• files (dict[str, bytes])

• scrubbed (list[str])

• skipped (list[SkippedFile])

files

Bundled file contents keyed by relative path.

Type:

dict[str, bytes]

scrubbed

Messages describing secret scrubbing that took place.

Type:

list[str]

skipped

Files that were not bundled, with reasons.

Type:

list[sharepack.collect.SkippedFile]

property total_bytes: int

Total size of all bundled files in bytes.

property db_bytes: int

Total size of bundled database files in bytes.

sharepack.collect.collect(project, include=(), exclude=())

Collect a project’s files for bundling, scrubbing secrets.

Parameters:

• project (Path) – Project root directory to walk.

• include (Sequence[str]) – Glob patterns (against posix relative paths) that force files into the bundle even if their extension is not bundled by default. Secret exclusions still apply.

• exclude (Sequence[str]) – Glob patterns that keep files out of the bundle; they take precedence over everything else.

Returns:

The bundled files plus scrub and skip diagnostics.

Return type:

CollectionResult

sharepack.build

Assemble the single-file HTML artifact.

class sharepack.build.BuildResult(out, adapter_name, n_files, size_bytes, scrubbed, skipped, warnings, db_files, db_bytes)

Everything a build produced, for reporting or programmatic use.

Parameters:

• out (Path)

• adapter_name (str)

• n_files (int)

• size_bytes (int)

• scrubbed (list[str])

• skipped (list[SkippedFile])

• warnings (list[str])

• db_files (list[str])

• db_bytes (int)

out

Path of the written HTML file.

Type:

pathlib.Path

adapter_name

Name of the detected framework adapter.

Type:

str

n_files

Number of files bundled.

Type:

int

size_bytes

Size of the written HTML file in bytes.

Type:

int

scrubbed

Messages describing secret scrubbing that took place.

Type:

list[str]

skipped

Files that were not bundled, with reasons.

Type:

list[sharepack.collect.SkippedFile]

warnings

Compatibility and size warnings.

Type:

list[str]

db_files

Relative paths of bundled database files.

Type:

list[str]

db_bytes

Total size of bundled database files in bytes.

Type:

int

sharepack.build.build(project, out, *, include=(), exclude=(), settings_module=None, app_spec=None, pyodide_version='0.26.4', pip_pin=None)

Bundle a project into a single self-contained HTML file.

Parameters:

• project (Path) – Project root directory (for Django: contains manage.py).

• out (Path) – Path of the HTML file to write.

• include (Sequence[str]) – Glob patterns forcing extra files into the bundle.

• exclude (Sequence[str]) – Glob patterns keeping files out of the bundle.

• settings_module (str | None) – Explicit Django settings module, bypassing detection from manage.py.

• app_spec (str | None) – Explicit module:variable locating a Flask or FastAPI app, bypassing entry-module scanning.

• pyodide_version (str) – Pyodide release loaded from the CDN at view time.

• pip_pin (str | None) – Override for the framework’s pip requirement string.

Returns:

A report of what was built.

Raises:

ProjectError – If project does not exist or is not a directory.

Return type:

BuildResult

Note

A DetectionError propagates from framework detection when no supported framework is found in project.

sharepack.adapters

Framework adapters.

Each adapter knows how to detect a framework and supply the template context that boots it inside Pyodide.

sharepack.adapters.detect(project, files, settings_module=None, app_spec=None)

Return the first adapter that recognizes the project, or raise.

Parameters:

• project (Path) – Project root directory.

• files (dict[str, bytes]) – Collected project files keyed by relative path.

• settings_module (str | None) – Explicit Django settings module, bypassing detection from manage.py.

• app_spec (str | None) – Explicit module:variable locating a Flask or FastAPI app, bypassing entry-module scanning.

Returns:

The adapter instance for the detected framework.

Raises:

DetectionError – If no adapter recognizes the project.

Return type:

DjangoAdapter | FlaskAdapter | FastAPIAdapter

Django adapter: detection, compatibility warnings, and boot script.

class sharepack.adapters.django.DjangoAdapter(settings_module, db_files, warnings, static_url='/static/')

Detects a Django project and supplies its Pyodide boot context.

Parameters:

• settings_module (str)

• db_files (list[str])

• warnings (list[str])

• static_url (str)

property describe: str

One-line description of what boots this app.

classmethod detect(project, files, settings_module=None, app_spec=None)

Recognize a Django project from its collected files.

Parameters:

• project (Path) – Project root directory.

• files (dict[str, bytes]) – Collected project files keyed by relative path.

• settings_module (str | None) – Explicit settings module; when given, detection from manage.py is skipped.

• app_spec (str | None) – Ignored; accepted for adapter interface parity.

Returns:

An adapter instance, or None if this is not a Django project.

Return type:

DjangoAdapter | None

template_context(pip_pin=None)

Return template placeholder values for the boot harness.

Parameters:

pip_pin (str | None) – Override for the framework’s pip requirement string (default: the built-in Django pin).

Returns:

Mapping of __PLACEHOLDER__ names to replacement strings.

Return type:

dict[str, str]