Resource store

Look up a document’s resource files by identifier or filename.

ResourceStore

class creator_studio_doc_format.core.ResourceStore(initial=None)[source]

Bases: MutableMapping[str, bytes]

The package’s resources, as a map from filename to bytes.

Saving writes exactly these entries to Data/. A resource that the JSON embeds, such as a Base64EncodedResource, is never in the store. Any method that adds a key raises ValueError unless the key is a flat filename: nonempty, not . or .., and without / or \.

A store from Package.open_lazy knows every name up front but reads each resource from the archive on first access, so len, iteration, and in read nothing. Reading isn’t safe across threads.

Parameters:
initial : Mapping[str, bytes] | None

The resources to start with, as a map from filename to bytes.

Keys match exactly, as in any mapping, so storing under a name that’s taken replaces that resource. unique_filename picks a free name instead:

>>> from creator_studio_doc_format.core import ResourceStore
>>> store = ResourceStore({"logo.png": b"old"})
>>> name = store.unique_filename("logo.png")
>>> store[name] = b"new"
>>> sorted(store)
['logo 2.png', 'logo.png']

The payload refers to a file from an IndirectResource, by its identifier or, when that’s absent, its filename. That name’s spelling can differ from the key’s, such as a name that a zip tool stored decomposed. Indexing and in miss it, and can_resolve and bytes_for find it:

>>> import unicodedata
>>> store = ResourceStore({unicodedata.normalize("NFD", "café.png"): b"png bytes"})
>>> "café.png" in store
False
>>> store.bytes_for("café.png")
b'png bytes'
close()[source]

Releases the backing archive and keeps only the resources already read.

Calling close again does nothing, and so does calling it on a store that isn’t lazy.

bytes_for(identifier)[source]

Returns the bytes for an indirect resource’s identifier or filename.

Matching tries these in order:

  • The exact key.

  • A canonically equivalent key, so NFC and NFD spellings match.

  • The only key with the same ASCII characters as the identifier, which tolerates mojibake in zip names.

The ASCII match can return a different file: é.png resolves to è.png when that’s the only key with the same ASCII characters. The resource check in Package.save accepts the same match.

Parameters:
identifier : str

An indirect resource’s identifier or filename.

Returns:

The bytes of the first key that matches.

Return type:

bytes

Raises:
  • KeyError – no key matches, or the ASCII match is ambiguous.

  • DocumentPackageError – a lazy store reads a corrupt member.

can_resolve(identifier)[source]

Returns a Boolean value that indicates whether a resource matches a name.

can_resolve matches names the way bytes_for does, and never reads bytes.

Parameters:
identifier : str

An indirect resource’s identifier or filename.

Returns:

True if bytes_for finds a resource for identifier, or False if it doesn’t.

Return type:

bool

unique_filename(preferred)[source]

Returns a filename that no resource uses, based on a preferred name.

Reading and saving never rename a resource, so this is only for a caller adding one. The number goes before the last ., so a.tar.gz becomes a.tar 2.gz and .hidden becomes " 2.hidden".

Parameters:
preferred : str

The filename to use if no entry has it.

Returns:

preferred if no entry has it, or else the first free numbered variant, such as name 2.ext.

Return type:

str

See also