lsdtools.publish reference

Immutable, transport-neutral descriptors for published LSD sites.

Package code owns the bytes in a static site directory.  This module validates and hashes those
bytes into the exact ``lsd.publish/v1`` manifest understood by the publish service, but deliberately
does not select a URL, implement HTTP, or start infrastructure.  Uploading is delegated to a public
client supplied by the caller (or, when the product provides one, by
``lsdtools.server.publish_client``).

The directory walk is fail-closed: only regular files and ordinary directories are accepted;
symbolic links, junctions/reparse points, traversal paths, and special files are rejected.  Limits
mirror the v1 service defaults so a package cannot spend unbounded work constructing a manifest the
service will refuse.

MAX_FILE_BYTES = 256 * 1024 * 1024

MAX_MANIFEST_BYTES = 4 * 1024 * 1024

MAX_MANIFEST_FILES = 20000

MAX_REVISION_BYTES = 2 * 1024 * 1024 * 1024

PUBLISH_SCHEMA_VERSION = 1

Public high-level client seam consumed by :func:`publish_directory`.

A client owns authentication, delta upload, retries, and generation compare-and-swap.  The SDK
supplies only a verified directory and immutable manifest.

publish_directory(self, directory: Path, *, manifest: PublishManifest, visibility: str, allowed_users: tuple[str, ...], expires_at: datetime | str | None, site_id: str | None, share_url: str | None=None) -> Any

allowed_users: tuple[str, ...]
directory: Path
expires_at: datetime | str | None
manifest: PublishManifest
self: (unannotated)
share_url: str | None
site_id: str | None
visibility: str

One immutable content-addressed file in a v1 publish manifest.

path: str

sha256: str

size: int

media_type: str

to_dict(self) -> dict[str, Any]

self: (unannotated)

Return a fresh JSON-safe v1 file descriptor.

A detached, immutable v1 manifest for one exact directory revision.

``title`` is site presentation metadata used by a client while creating or updating a site; it
is deliberately not part of the server's immutable content manifest.  ``content_sha256`` is
the SHA-256 of the canonical UTF-8 JSON returned by :meth:`to_dict`.

title: str

entrypoint: str

files: tuple[PublishFile, ...]

representations: tuple[PublishRepresentation, ...]

representations = ()

metadata: Mapping[str, Any]

metadata = field(default_factory=dict)

schema_version: int

schema_version = PUBLISH_SCHEMA_VERSION

content_sha256: str

content_sha256 = field(init=False)

from_directory(cls, directory: str | os.PathLike[str], *, title: str, entrypoint: str='index.html', representations: Iterable[PublishRepresentation]=(), metadata: Mapping[str, Any] | None=None, max_files: int=MAX_MANIFEST_FILES, max_file_bytes: int=MAX_FILE_BYTES, max_total_bytes: int=MAX_REVISION_BYTES, max_manifest_bytes: int=MAX_MANIFEST_BYTES) -> PublishManifest

cls: (unannotated)
directory: str | os.PathLike[str]
entrypoint: str
max_file_bytes: int
max_files: int
max_manifest_bytes: int
max_total_bytes: int
metadata: Mapping[str, Any] | None
representations: Iterable[PublishRepresentation]
title: str

Hash a directory into a deterministic, bounded v1 publish manifest.

Custom limits may lower, but never raise, the service's v1 limits.  They are useful for
package-specific policy and focused tests.

to_dict(self) -> dict[str, Any]

self: (unannotated)

Return a fresh JSON-safe server manifest (title and derived digest are client-side).

A package-owned semantic representation inside a generic published site.

id: str

kind: str

entrypoint: str | None

entrypoint = None

files: tuple[str, ...]

files = ()

metadata: Mapping[str, Any]

metadata = field(default_factory=dict)

version: int

version = PUBLISH_SCHEMA_VERSION

to_dict(self) -> dict[str, Any]

self: (unannotated)

Return a fresh JSON-safe v1 representation descriptor.

No public publish client is available in the active LSD runtime.

publish_directory(directory: str | os.PathLike[str], *, title: str, entrypoint: str='index.html', representations: Iterable[PublishRepresentation]=(), metadata: Mapping[str, Any] | None=None, visibility: str='private', allowed_users: Iterable[str]=(), expires_at: datetime | str | None=None, site_id: str | None=None, share_url: str | None=None, client: PublishClient | Any=None) -> Any

allowed_users: Iterable[str]
client: PublishClient | Any
directory: str | os.PathLike[str]
entrypoint: str
expires_at: datetime | str | None
metadata: Mapping[str, Any] | None
representations: Iterable[PublishRepresentation]
share_url: str | None
site_id: str | None
title: str
visibility: str

Publish one exact directory through the product's public client seam.

The facade constructs and verifies the manifest locally, then delegates the complete
prepare/upload/commit transaction.  It never performs HTTP itself.  Until a runtime provides
``lsdtools.server.publish_client()``, callers that need server publication must pass an explicit
client; local artifacts can still use :meth:`PublishManifest.from_directory` directly.