# lsdtools.publish reference
URL: https://lsd.tools/docs/sdk-lsdtools-publish
Updated: 2026-09-09

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `4ea39055732e8883c03ccfecf12af6ccebd2041a12ce1b843e4a769e200f5ef9`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
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.
```


## `lsdtools.publish.MAX_FILE_BYTES`

Kind: value. Source: `sdk/src/lsdtools/publish.py:50`.

```python
MAX_FILE_BYTES = 256 * 1024 * 1024
```


## `lsdtools.publish.MAX_MANIFEST_BYTES`

Kind: value. Source: `sdk/src/lsdtools/publish.py:53`.

```python
MAX_MANIFEST_BYTES = 4 * 1024 * 1024
```


## `lsdtools.publish.MAX_MANIFEST_FILES`

Kind: value. Source: `sdk/src/lsdtools/publish.py:52`.

```python
MAX_MANIFEST_FILES = 20000
```


## `lsdtools.publish.MAX_REVISION_BYTES`

Kind: value. Source: `sdk/src/lsdtools/publish.py:51`.

```python
MAX_REVISION_BYTES = 2 * 1024 * 1024 * 1024
```


## `lsdtools.publish.PUBLISH_SCHEMA_VERSION`

Kind: value. Source: `sdk/src/lsdtools/publish.py:49`.

```python
PUBLISH_SCHEMA_VERSION = 1
```


## `lsdtools.publish.PublishClient`

Kind: class. Source: `sdk/src/lsdtools/publish.py:667`.

Source docstring:

```text
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.
```


Declared bases: `Protocol`.

### `lsdtools.publish.PublishClient.publish_directory`

Kind: method. Source: `sdk/src/lsdtools/publish.py:674`.

```python
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
```


```python
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
```


## `lsdtools.publish.PublishFile`

Kind: class. Source: `sdk/src/lsdtools/publish.py:309`.

Source docstring:

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


### `lsdtools.publish.PublishFile.path`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:312`.

```python
path: str
```


### `lsdtools.publish.PublishFile.sha256`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:313`.

```python
sha256: str
```


### `lsdtools.publish.PublishFile.size`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:314`.

```python
size: int
```


### `lsdtools.publish.PublishFile.media_type`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:315`.

```python
media_type: str
```


### `lsdtools.publish.PublishFile.to_dict`

Kind: method. Source: `sdk/src/lsdtools/publish.py:327`.

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


```python
self: (unannotated)
```


Source docstring:

```text
Return a fresh JSON-safe v1 file descriptor.
```


## `lsdtools.publish.PublishManifest`

Kind: class. Source: `sdk/src/lsdtools/publish.py:394`.

Source docstring:

```text
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`.
```


### `lsdtools.publish.PublishManifest.title`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:402`.

```python
title: str
```


### `lsdtools.publish.PublishManifest.entrypoint`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:403`.

```python
entrypoint: str
```


### `lsdtools.publish.PublishManifest.files`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:404`.

```python
files: tuple[PublishFile, ...]
```


### `lsdtools.publish.PublishManifest.representations`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:405`.

```python
representations: tuple[PublishRepresentation, ...]
```


```python
representations = ()
```


### `lsdtools.publish.PublishManifest.metadata`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:406`.

```python
metadata: Mapping[str, Any]
```


```python
metadata = field(default_factory=dict)
```


### `lsdtools.publish.PublishManifest.schema_version`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:407`.

```python
schema_version: int
```


```python
schema_version = PUBLISH_SCHEMA_VERSION
```


### `lsdtools.publish.PublishManifest.content_sha256`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:408`.

```python
content_sha256: str
```


```python
content_sha256 = field(init=False)
```


### `lsdtools.publish.PublishManifest.from_directory`

Kind: method. Source: `sdk/src/lsdtools/publish.py:459`.

```python
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
```


```python
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
```


Source docstring:

```text
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.
```


### `lsdtools.publish.PublishManifest.to_dict`

Kind: method. Source: `sdk/src/lsdtools/publish.py:515`.

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


```python
self: (unannotated)
```


Source docstring:

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


## `lsdtools.publish.PublishRepresentation`

Kind: class. Source: `sdk/src/lsdtools/publish.py:339`.

Source docstring:

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


### `lsdtools.publish.PublishRepresentation.id`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:342`.

```python
id: str
```


### `lsdtools.publish.PublishRepresentation.kind`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:343`.

```python
kind: str
```


### `lsdtools.publish.PublishRepresentation.entrypoint`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:344`.

```python
entrypoint: str | None
```


```python
entrypoint = None
```


### `lsdtools.publish.PublishRepresentation.files`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:345`.

```python
files: tuple[str, ...]
```


```python
files = ()
```


### `lsdtools.publish.PublishRepresentation.metadata`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:346`.

```python
metadata: Mapping[str, Any]
```


```python
metadata = field(default_factory=dict)
```


### `lsdtools.publish.PublishRepresentation.version`

Kind: attribute. Source: `sdk/src/lsdtools/publish.py:347`.

```python
version: int
```


```python
version = PUBLISH_SCHEMA_VERSION
```


### `lsdtools.publish.PublishRepresentation.to_dict`

Kind: method. Source: `sdk/src/lsdtools/publish.py:380`.

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


```python
self: (unannotated)
```


Source docstring:

```text
Return a fresh JSON-safe v1 representation descriptor.
```


## `lsdtools.publish.PublishUnavailableError`

Kind: class. Source: `sdk/src/lsdtools/publish.py:100`.

Source docstring:

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


Declared bases: `RuntimeError`.

## `lsdtools.publish.publish_directory`

Kind: function. Source: `sdk/src/lsdtools/publish.py:757`.

```python
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
```


```python
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
```


Source docstring:

```text
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.
```